Payment Integration (Stripe)

Coras uses Stripe for payment processing with SCA (Strong Customer Authentication) support.

Async Flow (Web Checkout with 3DS/SCA)

Use this flow with PUT /v2/reservations (see Step 8, Option A).

1. Collect card details on your frontend using Stripe Elements.

2. Confirm reservations via PUT /v2/reservations to get the client_secret.

3. Confirm the payment using Stripe.js:

   const { error, paymentIntent } = await stripe.handleCardPayment(
       clientSecret,
       cardElement  // from Stripe Elements
   );

4. Retry until success: Keep calling stripe.handleCardPayment until the PaymentIntent status is requires_capture. If the status remains requires_payment_method, the card was declined or 3D Secure failed.

5. Webhook processing: Stripe sends a payment_intent.amount_capturable_updated event to Coras, which triggers the backend confirmation pipeline asynchronously.

6. Poll transaction status via GET /v2/users/{user_id}/transactions until status is PAID or FAILED.

Manual 3D Secure Handling

For custom 3D Secure flows (e.g., redirect-based):

const { error, paymentIntent } = await stripe.confirmPaymentIntent(
    clientSecret,
    {
        payment_method: paymentMethodId,
        return_url: 'https://your-app.com/payment-complete'
    }
);

Handle next_action from the response to display the 3D Secure challenge.

Sync Flow (Server-to-Server)

For distributors who are merchant of record, and therefore handle the customer's payment themselves, we also support confirming reservations using a saved payment method. In this case, the confirmation process is synchronous and there is no need to handle 3D Secure authentication on the client.

To use this confirmation method, a payment method such as a corporate credit card must be set up in advance by your Coras account manager. The payment method ID will be provided to you offline by the account manager and you can use it to confirm the reservation as shown below. A login and password will also be provided; these are required in order to obtain the authorization token needed to authenticate the confirmation request.

1. Obtain an authorization token by calling the authentication endpoint with the provided login and password.

2. Call the confirmation endpoint as shown, providing the obtained token in the Authorization header and the provided payment method ID in the request body.

The request will be processed synchronously and the response will indicate whether the transaction was successful or not; if successful, a 200 response status will be returned and the response body will include the transaction ID and user ID just like in the regular confirmation flow. However, there is no need to poll for the transaction status as in the regular confirmation flow since the transaction will have been processed immediately. If the transaction was not successful for any reason, an error message will be returned in the response body.

Use this flow with POST /v2/reservations/confirm (see Step 8, Option B).

1. Obtain an authorization token via POST /v2/auth with login and password.

2. Confirm reservations via POST /v2/reservations/confirm with the payment_method_id. The backend creates and confirms the PaymentIntent in a single synchronous operation.

3. No webhook needed — the Stripe webhook explicitly ignores synchronous transactions (those with synchronous=true in metadata).

4. Response is final — the 200 OK response confirms success. No polling required.