Provider Collection

If your agreement with your provider has the provider collect the premium, the premium is not added to your payment. The premium is charged by your provider, separately from your payment. You start the charge with POST /api/v1/insurance/orders/{orderId}/pay.

• Your payment is taken first. If you bound the order to a Lunixi payment, the premium can be charged only after that payment is captured. If your payment was not taken, no payment is sent to the provider.
• The premium is a separate charge. The buyer sees two separate charges: your payment and the provider's premium charge. A failed premium charge does not affect your payment.
• The premium does not go through your Lunixi payment. It is not part of your payment record or your payout; it is paid directly to the provider.
• The policy is requested automatically once the premium is charged. You do not call issue-policy.

This is available on the API path only. The Checkout Form offers only the products whose premium you collect.

Before you start

• In the panel, on the POS Center > Insurance page, set Who collects the premium to Provider collects for the product in your connection: Provider Connection › Products on this connection. The list shows only the methods the product supports.
• For this product, premiumCollectedBy is PROVIDER on quote options and orders.
• The provider's product charges the premium in one of two ways:

Flow

Charging the premium: POST /api/v1/insurance/orders/{orderId}/pay

Authentication

Because this endpoint can carry card data, it applies the same identity rule as the direct payment endpoints: a Bearer access token together with an Ed25519 request signature (Step-Up). Unlike the other insurance endpoints, the Authorization header is required.

Getting an access token and the Step-Up rules: Authentication. The token and the signing key must belong to the same account and the same environment.

Request

source lunixi-sign.sh
REQ_PATH="/api/v1/insurance/orders/<orderId>/pay"
BODY='{"card":{"cardNumber":"<card number>","expireMonth":"<MM>","expireYear":"<YYYY>","cvcNumber":"<security code>","cardHolderName":"<card holder>"},"returnUrl":"https://example.com/insurance/return"}'
lunixi_sign POST "$REQ_PATH" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Authorization: Bearer $LUNIXI_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: insurance-pay-1001" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

If the product charges on the provider's payment page (HOSTED), the body carries only returnUrl.

Card details

• If your account is not registered as PCI-DSS certified, a request to a card product returns 403 insurance.card.pci_required before the card is processed; no request is sent to the provider.
• The card is not stored by Lunixi. It is processed only during the request and forwarded to your provider. The security code is not kept anywhere.
• Card details never appear in responses, error messages, request logs or webhooks. An error response only says which field is invalid.
• If the card format is invalid (for example, the card number fails validation or the card has expired), the request returns 422 insurance.card.invalid; the invalid field is in details.field. No request is sent to the provider.

Response

When the request completes it returns 200. data carries two objects:

providerPayment:

The response does not include the provider's references, payment page address or error codes. Card details are never included in any form.

Outcomes

• An order has at most one open attempt at a time. While an open (PENDING, ACTION_REQUIRED, UNKNOWN) or successful attempt exists, no new attempt can be started; the same card is never charged twice.
• If the request fails before reaching the provider (e.g. the provider cannot be reached), no money moves: an error response is returned and the order goes back to its previous collection state. You can repeat the request after a while.

Retries and Idempotency-Key

• Charging the premium sends the offer to the provider and performs the charge in the same request. The request can take more than a minute; set your client timeout accordingly.
• After a timeout or a 5xx, repeat the request with the same Idempotency-Key and the same body. The same key returns the same attempt; the card is not processed again and no second charge is made.
• Generate a new key for a new attempt (e.g. another card after a declined charge).

Buyer action (nextAction)

If the provider needs the buyer to take a step for the charge (3-D Secure verification or the provider's payment page), the attempt becomes ACTION_REQUIRED and nextAction is returned. The same object is also on the order's nextAction field while the step is pending.

• redirectUrl is a Lunixi address (/api/v1/insurance/payments/{insurancePaymentId}/redirect). Lunixi redirects the buyer from there to the provider's page; the provider's page address is not shared with you.
• Open the address only in the buyer's browser. Once the return is processed, or when the attempt is no longer waiting for the buyer, the address returns 404 insurance.payment.not_found.
• If the buyer does not return by expiresAt, the outcome is confirmed with the provider.

Return

When the buyer completes the step on the provider's page, the provider returns to Lunixi. Then:

• If you sent returnUrl, the buyer is redirected to it with these query parameters added: insurancePaymentId, orderId, status.
• If you did not send returnUrl, the result is shown to the buyer as JSON. Send returnUrl on every request where you redirect the buyer.

Errors

Common codes: Flows › Responses and errors.

State conflict

Unsupported collection

Cancellation and refund

• You can cancel the policy with the cancel endpoint: Cancellation and Premium Refund › Policy cancellation.
• Because the premium is paid to the provider, it is not refunded through Lunixi; refund-premium returns 409 (reason: collected_by_provider) for these orders.
• Refunds you make from your own payment are not linked to insurance and do not cancel the policy.

Related

• Orders and Payment Binding: the order object and bind-payment
• Premium and Payment: flows where you collect the premium
• Insurance-Only Integration: the end-to-end flow without a Lunixi payment
• Webhook Events: insurance.policy.issued and insurance.policy.failed
• Error Codes: provider collection codes