Hosted Checkout

Here we describe how to use Inswitch APIs to integrate a merchant's marketplace or ecommerce to the Hosted Checkout payment solution. With this integration there is no need to manage the different actions types, all possibilities are mange by the white label checkout.

Hosted Checkout Flow

As described in the flow below, the merchant shoud:

• Get a token using the Auth-Service API.
• Generate a Hosted Checkout Instance using the API.
• Redirect the customer to the received url in the field "redirect".
• Once the payment is completed:
  • Customer is redirected back to the success or error URLs specified by the merchant.
  • A callback is sent to the merchant to inform about the update on the transaction status.

‍

API calls examples

Auth-Service API

‍

POST /protocol/openid-connect/token


curl --location --request POST 'https://{{baseUrl}}/auth-service/1.1/protocol/openid-connect/token' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username={{username}}' \
--data-urlencode 'password={{password}}'

‍

200 (OK)

{
    "access_token": "{{access_token}}",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "{{refresh_token}}",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "{{session_state}}",
    "scope": "profile email"
}

‍

Hosted Checkout API

POST /checkout

{
    "language": "es",
    "countryCode": "UY",
    "paymentExpiration": 600000,
    "pageExpiration": 7200000,
    "amount": 2000, 
    "currency": "UYU", 
    "purchaseItems": [
        {
            "item_name": "T-shirt blue",
            "item_quantity": 1,
            "item_amount": 100
        },
                {
            "item_name": "T-shirt green",
            "item_quantity": 2,
            "item_amount": 10
        }
    ],
    "senderKycInformation": {
        "name": {
            "firstName": "John",
            "lastName": "Doe",
            "fullName": "John Doe"
        },
        "idDocuments": [
            {
                "idType": "nationalId",
                "idNumber": "24971563792",
                "issuerCountry": "UY"
            }
        ],
        "dateOfBirth": "1980-02-22",
        "birthCountry": "UY",
        "nationality": "UY",
        "gender": "m",
        "entityType": "naturalPerson"
    },     
    "successUrl": "https://www.my-site-example.com/success",
    "errorUrl": "https://www.my-site-example.com/error",
    "termsAndConditionsUrl": "https://www.my-site-example.com/terms",
    "callbackUrl": "https://www.my-webhook-server.com/webhooks"
}

‍

200 (OK)

{
    "id": "b9e1dffb-9ce8-43b7-b6f8-d6de48c4ba62",
    "internalId": "hostedcheckout:B9E1DFFB-9CE8-43B7-B6F8-D6DE48C4BA62",
    "datePaymentStart": "2022-01-03T15:46:08+00:00",
    "datePaymentExpiration": "2022-01-03T17:46:08+00:00",
    "redirect": "{url}/checkout?id=b9e1dffb-9ce8-43b7-b6f8-d6de48c4ba62",
    "language": "es",
    "countryCode": "UY",
    "paymentExpiration": 600000,
    "pageExpiration": 7200000,
    "amount": 2000,
    "currency": "UYU",
    "purchaseItems": [
        {
            "item_name": "T-shirt blue",
            "item_quantity": 1,
            "item_amount": 100
        },
                {
            "item_name": "T-shirt green",
            "item_quantity": 2,
            "item_amount": 10
        }
    ],
    "senderKycInformation": {
        "name": {
            "firstName": "John",
            "lastName": "Doe",
            "fullName": "John Doe"
        },
        "idDocuments": [
            {
                "idType": "nationalId",
                "idNumber": "24971563792",
                "issuerCountry": "UY"
            }
        ],
        "dateOfBirth": "1980-02-22",
        "birthCountry": "UY",
        "nationality": "UY",
        "gender": "m",
        "entityType": "naturalPerson"
    },
    "successUrl": "https://www.my-site-example.com/success",
    "errorUrl": "https://www.my-site-example.com/error",
    "termsAndConditionsUrl": "https://www.my-site-example.com/terms",
    "callbackUrl": "https://www.my-webhook-server.com/webhooks"
}

‍

Transaction Callback

PUT {callbackUrl}

 {
  "amount": "120.0000000",
  "confirmed": true,
  "country": "UY",
  "creationDate": "2022-01-03T15:55:59.849323Z",
  "creditParty": {
    "data": {
      "ACCOUNT_ID": "1000603",
      "CURRENCY": "UYU"
    },
    "paymentMethodReference": "3333373130352D313030302D32303033",
    "type": "emoney-uyu",
    "typeClass": "emoney",
    "typeCountry": "UY"
  },
  "currency": "UYU",
  "debitParty": {
    "data": {},
    "type": "redpagos-uy",
    "typeClass": "cash",
    "typeCountry": "UY"
  },
  "descriptionText": "Hosted checkout",
  "fx": {},
  "geoCode": "37.423825,-122.082900",
  "metadata": [],
  "modificationDate": "2022-01-03T15:56:00.016270Z",
  "recipientKyc": {},
  "requestDate": "2022-01-03T15:57:53.278Z",
  "requestingOrganisationTransactionReference": "9b5bc9d2-47ae-48e7-955b-691e237f6b97",
  "requiredAction": {
    "actionType": "paymentcode",
    "data": {
      "additionalInformation": [],
      "code": "DP92870X908"
    },
    "expirationDate": "2022-01-05T15:57:53Z",
    "relatedPaymentMethodData": {
      "paymentMethodType": "redpagos-uy",
      "paymentMethodTypeClass": "cash",
      "paymentMethodTypeCountry": "UY",
      "paymentMethodTypeDescription": "Redpagos"
    },
    "status": "active"
  },
  "senderKyc": {
    "name": {
            "firstName": "John",
            "lastName": "Doe",
            "fullName": "John Doe"
        },
        "idDocuments": [
            {
                "idType": "nationalId",
                "idNumber": "24971563792",
                "issuerCountry": "UY"
            }
        ],
        "dateOfBirth": "1980-02-22",
        "birthCountry": "UY",
        "nationality": "UY",
        "gender": "m",
        "entityType": "naturalPerson"
  },
  "subType": "",
  "transactionReference": "1092242",
  "transactionStatus": "finished",
  "type": "merchantpay"
}

‍

Using Hosted Checkout API

API specification is avaialble here: Hosted Checkout

‍

‍

‍

‍