Checkout Integration

Checkout Integration

To perform a payment integration with redirection, follow these steps:

1. Service authentication

2. Register checkout

3. Redirect to payment checkout

4. Success or Cancellation Redirect

1.- Service Authentication

Copy the API access credentials to call the OrkestaPay authentication service and obtain an access token, which will be used for subsequent service calls.

curl --request POST \
     --url https://api.sand.orkestapay.com/v1/oauth/tokens \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "client_id": "REPLACE_WITH_YOUR_CLIENT_ID",
     "client_secret": "REPLACE_WITH_YOUR_CLIENT_SECRET",
     "grant_type": "client_credentials"
}
'

{
    "token_type": "Bearer",
    "expires_in": 1800,
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIwenJMTnEwbzBab1R4NTlaeWVPaTI1RGxZLWl6cV91SVFSLThWS0RaWjlFIn0.eyJleHAiOjE2Njk4NTAzNTAsImlhdCI6MTY2OTg1MDE3MCwianRpIjoiMWI4MWZhMDItMzk2ZC00NGNjLWJlMzctZGU4ZWQyODg2MTEyIiwiaXNzIjoiaHR0cHM6Ly9kZXYtYXV0aC56ZW5raS5maS9hdXRoL3JlYWxtcy9wYnciLCJzdWIiOiIxMjgyNjJhOS00NDgxLTQ4OGItYTczNi1iNmI5MTA1NjQ4MzQiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiI1MDg3ODE3MDhjNzk5MTE5NTJkZGJlYWZkZjM5NjNmNTcxYjNjYzE4YzE5YmNkY2YiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbImh0dHBzOi8vcG9ydGFsLWRldi56ZW5raS5maSJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiYXBpIiwiYXBpX3plbmtpcGF5Il19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImNsaWVudEhvc3QiOiIzNS44NS4yMy4xOTAiLCJjbGllbnRJZCI6IjUwODc4MTcwOGM3OTkxMTk1MmRkYmVhZmRmMzk2M2Y1NzFiM2NjMThjMTliY2RjZiIsInByZWZlcnJlZF91c2VybmFtZSI6InNlcnZpY2UtYWNjb3VudC01MDg3ODE3MDhjNzk5MTE5NTJkZGJlYWZkZjM5NjNmNTcxYjNjYzE4YzE5YmNkY2YiLCJjbGllbnRBZGRyZXNzIjoiMzUuODUuMjMuMTkwIn0.Ds5eQ-tkn4ckTUHI-mrJn6eYBaUa-6uZNxzrGRfYc5neI1TvB2RHu_IDsktDVi9XdR5P_P0mSpzar9jWJOrxxA_csTnn9ZXy8rDeRqjMm9j03xWz-tZcxiUM6xvN1qvOeBGFzISIP9y24jyL0Jqpl8YhkSGF8xBfFvfhOvEMvgLby5n7dTDoZVi2Bw8G1kZJKPejmBu8MJetl08OoVk_obp6lW3YetQPYTwsutOc_yIxBIUkPSH2Gj3wpBxBa8EfMES4J1SAT7Thpw_CmZ_PNB9rEDUJI4bzE7QM2Z0n4LNXzbo5JFuWudKwfhqOcryH0slmHOamJgbtR5EGryf8LQ"
}

2.- Register checkout

After obtaining the access token, register a checkout by calling the create checkout service in OrkestaPay’s API. Provide URLs for redirection upon successful payment completion or cancellation.

Request to the service

You must call the "create checkout" service and as part of the request, you must send a couple of URLs that will serve to redirect the buyer once the payment has been completed (REPLACE_WITH_YOUR_SUCCESS_URL), or it has been canceled (REPLACE_WITH_YOUR_CANCEL_URL). In addition, the Authorization header must be sent and the value is the "access_token" obtained in step 1. You'll need to look for the text "REPLACE_WITH_YOUR_ACCESS_TOKEN" in the script below and replace it with the JWT token.

curl --request POST \
     --url https://api.sand.orkestapay.com/v1/checkouts \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer REPLACE_WITH_YOUR_ACCESS_TOKEN' \
     --data '
{
    "completed_redirect_url": "REPLACE_WITH_YOUR_SUCCESS_URL",
    "canceled_redirect_url": "REPLACE_WITH_YOUR_CANCEL_URL",
    "allow_save_payment_methods": false,
    "locale": "ES_LATAM",
    "order": {
        "merchant_order_id": "1366656595193",
        "currency": "MXN",
        "subtotal_amount": 1000,
        "country_code": "MX",
        "discounts": [
            {
                "amount": 10
            }
        ],
        "total_amount": 990,
        "products": [
            {
                "id": "7197",
                "name": "Pantalla TCL Smart TV Serie A3 A343 HD Android TV 40",
                "quantity": 1,
                "unit_price": 1000
            }
        ],
        "customer": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@yopmail.com"
        }
    }
}
'

Service response

When you register a checkout, the following information will be returned. For the moment and for the purposes of the example, only the checkout_redirect_url will be of interest.

{
    "checkout_id": "chk_e69283cb55814402b9372a2f834cc8a8",
    "checkout_redirect_url": "https://checkout.dev.orkesta.io/#/checkout/chk_e69283cb55814402b9372a2f834cc8a8/6f2d8077c669f0512cb655c1f2d19b3cc020f5fd8b17152e0d3de675575e8f69",
    "completed_redirect_url": "https://example.com/complete",
    "canceled_redirect_url": "https://example.com/cancel",
    "allow_save_payment_methods": false,
    "locale": "ES_LATAM",
    "placed_at": "1713480514319",
    "order": {
        "order_id": "ord_a73c91e6f6f949a3a39c9557f353d308",
        "status": "CREATED",
        "expires_at": "1713566914212",
        "merchant_order_id": "1366656595193",
        "country": "México",
        "country_code": "MX",
        "currency": "MXN",
        "taxes": [],
        "discounts": [
            {
                "amount": 10
            }
        ],
        "subtotal_amount": 1000,
        "total_amount": 990,
        "products": [
            {
                "product_id": "7197",
                "quantity": 1,
                "unit_price": 1000,
                "name": "Pantalla TCL Smart TV Serie A3 A343 HD Android TV 40"
            }
        ],
        "customer": {
            "customer_id": "cus_414bae1120844159bf10f1d6c7b30d74",
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@yopmail.com",
            "created_at": "1713480514197",
            "updated_at": "1713480514197"
        },
        "placed_at": "1713480514267",
        "metadata": {}
    }
}

3.- Redirection to the payment checkout

Redirect the buyer to the checkout URL to complete the purchase. The checkout design can be customized with your store’s branding via the OrkestaPay dashboard.

4.- Redirect success or cancellation

The buyer can cancel and return to the store or complete the payment and be redirected to the specified URL during checkout registration. It is recommended to include parameters in these URLs to manage the order status in your integration.

NOTE: It is recommended that in this pair of URLs, parameters that you provide allow your integration to manage the behavior and status of the order/purchase order.