Guides
PricingSales

Capture a payment instrument and charge with a saved instrument

How merchants create a checkout, use a zero-amount session to collect buyer payment details, and charge later with a merchant-initiated charge.

Capture a payment instrument and charge with a saved instrument

This guide is for merchants integrating the Payin API. It describes how to create a checkout, use a zero-amount checkout to capture a buyer’s payment method when you are not collecting a payment yet, and then charge the checkout using the buyer’s saved checkout instrument with a merchant-initiated PUT.

Prerequisites

  • Merchant API access and a Bearer token with the Merchant role.
  • Your merchant account must be allowed to charge on behalf of a buyer (merchant-initiated charge). If you receive a forbidden response on the charge endpoint, contact Payment Labs to confirm this is enabled for your account.
  • The checkout must be associated with a buyer (userId on the checkout) before a merchant charge can succeed. The hosted checkout flow links the buyer when they sign in or complete the session.

1. Create a checkout

Create a checkout session with the Create a new checkout API (POST /checkouts).

Provide at least alias, termsOfServiceUrl, privacyPolicyUrl, buyer.email, currency, and amount. The response includes id and links.checkout (and links.embeddable if you embed the flow).

2. Zero-amount checkout (capture payment details only)

To collect a payment method without charging a positive amount, set:

  • "amount": 0

Authenticated buyers only: For zero-amount checkouts, the API enforces authenticated buyers only (AUTHENTICATED_ONLY). If you omit authenticationOptions, it defaults to AUTHENTICATED_ONLY for zero. That means guest checkout is not available for these sessions: the buyer must sign in or create an account so they can save a payment method to their profile.

Send the buyer to the hosted experience using links.checkout or links.embeddable so they can complete the flow and add or confirm their payment method.

3. Discover the buyer’s saved checkout instrument

When you need the identifier of a saved instrument for a later charge, use the List available checkout instruments endpoint (GET /checkouts/{checkoutId}/checkout-instruments/available). Each item includes an id you can use as checkoutInstrumentId when charging.

Note: For zero-amount vault-only sessions, the platform may not expose saved (on-file) instruments in this list the same way as for payable checkouts. If you do not see a checkoutInstrumentId yet, ensure the buyer has finished the hosted flow and that your integration uses a checkout that is ready for merchant charge (see Charge Checkout).

4. Charge the checkout (merchant-initiated)

After the buyer has a saved instrument available for your checkout, charge the checkout using the Charge Checkout endpoint:

PUT /checkouts/{checkoutId}/charge

Request body (minimal case using a saved instrument):

{
  "checkoutInstrumentId": "<checkout-instrument-id>"
}

The response returns transaction details for the charge (for example id, status, and related fields on the transaction object).

5. Related topics


Updated 1 day ago