Refund

Return the money of a paid checkout to the customer, in full or in part.

Before you begin

• An API key and a Bearer token, as in Simple payment, steps 1 and 2.
• The id, currency and external_id of the paid checkout. They are in the create checkout response and in the checkout.succeeded webhook.

Steps

1. Create the refund

   Send the checkout id as checkout_id. amount is optional: leave it out to refund the whole remaining amount, or send it in cents for a partial refund. Depending on the payment method, only a full refund may be possible.

   This request refunds 1.00 EUR of the 3.00 EUR checkout from Simple payment:

   Command Line

   curl --location --request POST 'https://sandbox.payout.one/api/v1/refunds' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer SFMyNTY.EXAMPLE-TOKEN.dGhpcy1pcy1hLWZha2Utc2lnbmF0dXJlLWV4YW1wbGU' \
   --data-raw '{
       "checkout_id": 141447,
       "amount": 100,
       "iban": "SK3112000000198742637541",
       "statement_descriptor": "Refund for order 1001",
       "nonce": "YmNHNzliRGhPMnNkNXVPZA",
       "signature": "755b4f84704efd8e69c4acf727f5f2f4a259f21163357e14ec2ac6ff014f45c3"
   }'
   

   Refund payment lists all fields.

   The signature combines values from the request with values of the checkout:

   • amount: as sent in the request; if you leave it out, the checkout amount in cents
   • currency and external_id: of the checkout; you don't send them in the request
   • iban: as sent in the request; an empty string if you leave it out
   • nonce: as sent in the request
   • client_secret: of your API key

   Join them with | and hash the string with SHA-256:

   TEXT

   Pattern: amount|currency|external_id|iban|nonce|client_secret
   Input:   100|EUR|order-1001|SK3112000000198742637541|YmNHNzliRGhPMnNkNXVPZA|q3dpHpYtDrH-KmGD4HMn5OTEx6IsZPBokQ8CqMONWqMSEePWy9bXd3Ua3KvO7f6C
   SHA-256: 755b4f84704efd8e69c4acf727f5f2f4a259f21163357e14ec2ac6ff014f45c3
   

   Without amount and iban, the input for the same checkout would be 300|EUR|order-1001||YmNHNzliRGhPMnNkNXVPZA|q3dpHpYtDrH-KmGD4HMn5OTEx6IsZPBokQ8CqMONWqMSEePWy9bXd3Ua3KvO7f6C.

   Note

   Send the hash in lowercase hex. Some libraries return uppercase hex; convert it to lowercase.

2. Check the response

   The response is the new refund. It starts with status pending.

   JSON

   {
       "id": 52332,
       "object": "refund",
       "amount": 100,
       "currency": "EUR",
       "external_id": "order-1001",
       "idempotency_key": null,
       "customer": {
           "first_name": "John",
           "last_name": "Doe",
           "name": "John Doe",
           "email": "[email protected]",
           "phone": "+421900000000",
           "note": null
       },
       "status": "pending",
       "metadata": {},
       "statement_descriptor": "Refund for order 1001",
       "created_at": 1759748400,
       "nonce": "Rzd5R1U2emlvSTlKeU85aQ",
       "signature": "91ed0b376d9305eb86583790d0f7699454f6f583ec8888e3192db11332773c8e"
   }
   

   Payout also sends a checkout.refund_requested webhook to your notify URL.

Next steps

• Errors such as an unpaid or already refunded checkout are listed in Refund payment.
• For checkouts split by offer_id, see Transaction splitting.