Simple payment

Simple example how to make simple payment

1. Generate api key and secret

   • You can do it in backoffice(Sandbox or Production) after you have already created account.
   • It's required to add notify url before api key is generated. This url will be used for sending webhook notifications (POST HTTP Requests) about state of checkouts and other events.

2. Make authorization call to get Bearer token

   Command Line

   curl --location --request POST 'https://sandbox.payout.one/api/v1/authorize' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --data-raw '{
    "client_id": "DC995618-7ED8-4070-9DA0-48B6F86551C3",
    "client_secret": "q3dpHpYtDrH-KmGD4HMn5OTEx6IsZPBokQ8CqMONWqMSEePWy9bXd3Ua3KvO7f6C"
   }'
   

   Response of this call looks like this:

   JSON

   {
    "token": "SFMyNTY.g2gDYSFuBgCaSXELfgFiAAFRgWnBcvEfet1jIr9OPF984RGTKu-8HcHPQKJitk_kJKiU",
    "valid_for": 6000
   }
   

3. Create checkout with details from your order. It's POST HTTP call with JSON body. Call have to contain also Authorization header with Bearer token from previous step

   Command Line

   curl --location --request POST 'https://sandbox.payout.one/api/v1/checkouts' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer SFMyNTY.g2gDYSFuBgCaSXELfgFiAAFRgA.WnBcvEfet2jJr4OPF984RGTKu-8HcHPQKJitk_kJKiU' \
   --header 'Accept: application/json' \
   --header 'Idempotency-Key: 74775d02-745f-4198-cf3c-be9f1971dabe' \
   --data-raw '{
       "amount": "300",
       "currency": "EUR",
       "iban": "SK5511000000002611391222",
       "customer": {
           "first_name": "John",
           "last_name": "Doe",
           "email": "[email protected]",
           "phone": "123-4567890"
       },
       "billing_address": {
           "name": "John Doe",
           "address_line_1": "Billing Address Line 1",
           "address_line_2": "Billing Address Line 2",
           "city": "Billington",
           "postal_code": "BL92883",
           "country_code": "GB"
       },
       "shipping_address": {
           "name": "John Doe",
           "address_line_1": "Shipping Address Line 1",
           "address_line_2": "Shipping Address Line 2",
           "city": "Shippington",
           "postal_code": "W153KF",
           "country_code": "GB"
       },
       "products": [
           {
               "name": "Product 1",
               "unit_price": 100,
               "quantity": 3
           }
       ],
       "external_id": "74775d02-745f-4198-cf3c-be9f1971dabe",
       "nonce": "1474e979-9f64-012a-6d8a-f00957d4a4a0",
       "metadata": {
           "note": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been."
       },
       "redirect_url": "https://some-eshop.local/merchant_redirect_url",
       "signature": "ef30790284ffb097e7e4b0d1162db605f97f52c59f0cfc877870bde4e61f7d77"
   }'
   

   Note

   Amount is in cents (EUR), so 3 EUR is 300. It's same for other currencies, for example 300 CZK is 30000.

   Signature is generated from string with this pattern:

   Code

   amount|currency|external_id|nonce|client_secret
   

   For this specific request:

   Code

   300|EUR|74775d02-745f-4198-cf3c-be9f1971dabe|1474e979-9f64-012a-6d8a-f00957d4a4a0|q3dpHpYtDrH-KmGD4HMn5OTEx6IsZPBokQ8CqMONWqMSEePWy9bXd3Ua3KvO7f6C
   

   This string is hashed with SHA256 and encoded with Base16 to this form:

   Code

   ef30790284ffb097e7e4b0d1162db605f97f52c59f0cfc877870bde4e61f7d77
   

   Note

   Some algorithms implementations generate output in UPPERCASE form so please change all characters into lowercase form.

4. Verify response from created checkout call

   Response body from previous step contain signature attribute which has to be verified to be sure answer is from Payout systems. Process is similar like for signature for creating checkout. Signature has to be generated and compared with signature from response, they have to be same.

   JSON

   {
       "amount": 300,
       "billing_address": {
           "address_line_1": "Billing Address Line 1",
           "address_line_2": "Billing Address Line 2",
           "city": "Billington",
           "country_code": "GB",
           "name": "John Doe",
           "postal_code": "BL92883"
       },
       "checkout_url": "https://sandbox.payout.one/checkouts/U0ZNeU5UWS5nMmdEZEFBQUFBSmtBQU5oY0dsaElXUUFBbWxrWWdBQ0tJZHVCZ0JtS1hrTGZnRmlBQUZSZ0EuR2xYdDlsZjY4NDNIY2xaUXFXTFBGdHFETWZDNmw3SXViOG1wM0VXYi1nOA",
       "currency": "EUR",
       "customer": {
           "email": "[email protected]",
           "first_name": "John",
           "last_name": "Doe",
           "name": "John Doe",
           "note": null,
           "phone": "123-4567890"
       },
       "external_id": "74775d02-745f-4198-cf3c-be9f1971dabe",
       "id": 141447,
       "idempotency_key": "74775d02-745f-4198-cf3c-be9f1971dabe",
       "metadata": {
           "note": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been."
       },
       "nonce": "WWdVaGk4d3ZqeHFOTjM4Qw",
       "object": "checkout",
       "payment": null,
       "products": [
           {
               "name": "Product 1",
               "quantity": 3,
               "unit_price": 100
           }
       ],
       "redirect_url": "https://some-eshop.local/merchant_redirect_url",
       "shipping_address": {
           "address_line_1": "Shipping Address Line 1",
           "address_line_2": "Shipping Address Line 2",
           "city": "Shippington",
           "country_code": "GB",
           "name": "John Doe",
           "postal_code": "W153KF"
       },
       "signature": "c1bbd464676a186efb320febbb1d8d7f24fbf96783ce7e64f0cfe6b679ff14af",
       "status": "processing"
   }
   

   Signature is generated from string with this pattern:

   Code

   amount|currency|external_id|nonce|client_secret
   

   For this specific response:

   Code

   300|EUR|74775d02-745f-4198-cf3c-be9f1971dabe|WWdVaGk4d3ZqeHFOTjM4Qw|q3dpHpYtDrH-KmGD4HMn5OTEx6IsZPBokQ8CqMONWqMSEePWy9bXd3Ua3KvO7f6C
   

   This string is hashed with SHA256 and encoded with Base16 to this form:

   Code

   c1bbd464676a186efb320febbb1d8d7f24fbf96783ce7e64f0cfe6b679ff14af
   

   Note

   Some algorithms implementations generate output in UPPERCASE form so please change all characters into lowercase form.

5. Redirect customer to redirect url from url from checkout_url attribute from response.

6. Customer is redirected to redirect url after process of payment is successful or failed. Redirect url is defined in step with creating checkout as redirect_url attribute.

7. Information about state of checkout / customer payment is not delivered with redirection but asynchronously with Webhook POST callback. This callback is sent to notify url. It's required to verify signature to verify that call is coming from Payout System. Signature has to be generated manually and compared with signature from signature attribute from webhooks. They have to be exactly the same.

   Webhook with successful checkout:

   JSON

   {
       "data":
       {
           "id": 141209,
           "amount": 300,
           "object": "checkout",
           "status": "succeeded",
           "is_status_final": true,
           "payment":
           {
               "fee": 8,
               "net": 292,
               "object": "payment",
               "status": "successful",
               "created_at": 1635412755,
               "failure_reason": "",
               "payment_method": "PayU"
           },
           "currency": "EUR",
           "customer":
           {
               "email": "[email protected]",
               "first_name": "John",
               "last_name": "Doe"
           },
           "metadata": null,
           "card_mask": "401200******1120",
           "external_id": "1472",
           "redirect_url": "https://some-eshop.local/merchant_redirect_url"
       },
       "type": "checkout.succeeded",
       "nonce": "QjJqWEtiVDBNSmMyTm11dg",
       "object": "webhook",
       "signature": "f3b8264f42930eff215c6570f4bcdd50bcedcaf3c6da8ccfd301c6de41f36607",
       "external_id": "1472"
   }
   

   Note

   The is_status_final field indicates whether the checkout has reached a terminal state and will no longer change. For succeeded checkouts it is always true. For expired checkouts it becomes true only after 6 days from expiration (to allow time for any pending bank transfer payments to arrive and be reconciled).

   Signature is generated from string with this pattern:

   Code

   external_id|type|nonce|client_secret
   

   For this specific request:

   Code

   74775d02-745f-4198-cf3c-be9f1971dabe|checkout.succeeded|QjJqWEtiVDBNSmMyTm11dg|q3dpHpYtDrH-KmGD4HMn5OTEx6IsZPBokQ8CqMONWqMSEePWy9bXd3Ua3KvO7f6C
   

   This string is hashed with SHA256 and encoded with Base16 to this form:

   Code

   f3b8264f42930eff215c6570f4bcdd50bcedcaf3c6da8ccfd301c6de41f36607
   

   Note

   Some algorithms implementations generate output in UPPERCASE form so please change all characters into lowercase form.

8. Merchant's order can be marked as paid after webhook type checkout.succeeded is received and verified. The is_status_final: true field in the payload confirms the checkout will not change further.

   Optionally, you can also listen for the checkout.finalized webhook event, which is sent at the moment is_status_final transitions to true. This is useful for expired checkouts where finalization happens 6 days after expiration. The checkout.finalized event is available on request — contact support to enable it for your account.

Test cards