Capture and cancel

Authorize an amount on the customer's card first, then capture all of it or only a part, or cancel the authorization. This helps when some ordered items turn out to be unavailable, or when the final price is lower than the authorized amount, for example for a car rental.

Before you begin

• Pre-authorization works with card payments and must be enabled for your account; contact support.
• An API key and a Bearer token, as in Simple payment, steps 1 and 2.

Capture

1. Create a pre-authorization checkout

   Create the checkout as in Simple payment, with "mode": "pre_authorization" and the amount you want to authorize, and redirect the customer to checkout_url from the response.

   Command Line

   curl --location --request POST 'https://sandbox.payout.one/api/v1/checkouts' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer SFMyNTY.EXAMPLE-TOKEN.dGhpcy1pcy1hLWZha2Utc2lnbmF0dXJlLWV4YW1wbGU' \
   --header 'Idempotency-Key: 77746fd3-3b82-491f-9fe7-8612e6314a45' \
   --data-raw '{
       "amount": 300,
       "currency": "EUR",
       "mode": "pre_authorization",
       "customer": {
           "first_name": "John",
           "last_name": "Doe",
           "email": "[email protected]"
       },
       "external_id": "order-4001",
       "nonce": "MnFLUkdUWENlWTdqVHdRUg",
       "redirect_url": "https://eshop.example.com/payment/redirect",
       "signature": "f956eb7122d8a1822a4c7daaa84bb71a2a3de5e02f3f0da84cc3c79f67598558"
   }'
   

   amount is in cents: 300 is 3.00 EUR. Sign the request as in Simple payment:

   TEXT

   Pattern: amount|currency|external_id|nonce|client_secret
   Input:   300|EUR|order-4001|MnFLUkdUWENlWTdqVHdRUg|q3dpHpYtDrH-KmGD4HMn5OTEx6IsZPBokQ8CqMONWqMSEePWy9bXd3Ua3KvO7f6C
   SHA-256: f956eb7122d8a1822a4c7daaa84bb71a2a3de5e02f3f0da84cc3c79f67598558
   

   Note

   Signatures are SHA-256 hashes in lowercase hex. Some libraries return uppercase hex; convert it to lowercase before you send or compare it.

2. Receive the checkout.pre_authorized webhook

   When the customer authorizes the amount, Payout sends checkout.pre_authorized to your notify URL. Nothing is charged yet: is_status_final is false because the checkout can still be captured or cancelled. Use type to tell this webhook apart from a completed payment.

   checkout.pre_authorized payload:

   JSON

   {
       "external_id": "order-4001",
       "object": "webhook",
       "type": "checkout.pre_authorized",
       "data": {
           "object": "checkout",
           "id": 141701,
           "external_id": "order-4001",
           "amount": 300,
           "currency": "EUR",
           "redirect_url": "https://eshop.example.com/payment/redirect",
           "customer": {
               "first_name": "John",
               "last_name": "Doe",
               "email": "[email protected]",
               "card_number_masked": ""
           },
           "payment": null,
           "metadata": {},
           "status": "succeeded",
           "is_status_final": false
       },
       "nonce": "WnF1bXBtMDhoc0U4Sk5wag",
       "signature": "b40cd606d4867aba4e8b56ce0ab2b377f92b4e96f18b5fbf9390ab37fc97880d"
   }
   

   Verify the signature as in Simple payment:

   TEXT

   Pattern: external_id|type|nonce|client_secret
   Input:   order-4001|checkout.pre_authorized|WnF1bXBtMDhoc0U4Sk5wag|q3dpHpYtDrH-KmGD4HMn5OTEx6IsZPBokQ8CqMONWqMSEePWy9bXd3Ua3KvO7f6C
   SHA-256: b40cd606d4867aba4e8b56ce0ab2b377f92b4e96f18b5fbf9390ab37fc97880d
   

3. Capture the funds

   Charge the customer's card with the whole authorized amount or a part of it: send one of these requests with the checkout id in the path.

   Full capture, with an empty body:

   Command Line

   curl --location --request POST 'https://sandbox.payout.one/api/v1/checkouts/141701/capture' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer SFMyNTY.EXAMPLE-TOKEN.dGhpcy1pcy1hLWZha2Utc2lnbmF0dXJlLWV4YW1wbGU' \
   --data-raw '{}'
   

   Partial capture, with amount in cents. It can't be larger than the authorized amount.

   Command Line

   curl --location --request POST 'https://sandbox.payout.one/api/v1/checkouts/141701/capture' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer SFMyNTY.EXAMPLE-TOKEN.dGhpcy1pcy1hLWZha2Utc2lnbmF0dXJlLWV4YW1wbGU' \
   --data-raw '{
       "amount": 150
   }'
   

   A successful capture responds with:

   JSON

   "captured"
   

4. Receive the checkout.captured webhook

   After the funds are captured, Payout sends checkout.captured. The amount in its payload is the captured amount.

Cancel

Cancel a pre-authorized checkout when you won't charge the customer, for example because a product or service can't be delivered. The authorized amount is released and the customer isn't charged.

Send a DELETE request with the checkout id in the path:

curl --location --request DELETE 'https://sandbox.payout.one/api/v1/checkouts/141701' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer SFMyNTY.EXAMPLE-TOKEN.dGhpcy1pcy1hLWZha2Utc2lnbmF0dXJlLWV4YW1wbGU'

A successful cancellation responds with "pre-auth canceled". The checkout status changes to failed and Payout sends a checkout.canceled webhook.

Next steps

• Try the flow in the sandbox with the test cards.
• To return money after a capture, create a refund.