Skip to content

Authorization And Capture

Create A Credit Card Authorization

Authorizing a card payment allows you to reserve funds in a customer's bank account days before the actual payment occurs – for example when making hotel reservations.

To make it work, you need to create an authorization first, and then capture it.

HTTP Request

POST /v1/payments/charges/card

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "amount": 1000,
    "country": "PE",
    "currency": "PEN",
    "paymentMethod": "CREDIT_CARD",
    ...  # other basic request fields
    "capture": false,
    "subMerchantId": "UUID",
    ...  # other basic request fields
}
Response
{
    "transferStatusCode": 200,
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "paymentMethod": "CREDIT_CARD",
    "amount": 1000,
    "currency": "PEN",
    "finalAmount": 1000,
    "finalCurrency": "PEN",
    "country": "PE",
    "createTime": "2022-03-01 17:53:18 GMT-08:00",
    "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
    ...  # other basic response fields
    "transferDetails": {
        "card": {
            "cardInfo": {
                "cardHolderName": "card_holder_name",
                "expirationMonth": 9,
                "expirationYear": 2024,
                "brand": "VISA",
                "bin": "458124",
                "last4": "0000"
            },
            "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237"
        }
    },
    "transferStatus": "AUTHORIZED",
    "description": "this is a test pay",
    "subMerchantId": "UUID"
}

HTTP Headers Details

Key Value
Authorization "bearer" + " " + {{access_token}}
x-api-key {{api_key}}

Request Body Parameters

Parameter Required Type Description
capture Boolean Must set to false to create an authorization.
subMerchantId String The sub merchant ID. Required for PSPs.

Capture An Authorization

HTTP Request

POST /v1/payments/charges/card/capture/{{idempotencyKey}}

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "amount": 1000
}
Response
{
    "transferStatusCode": 200,
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "paymentMethod": "CREDIT_CARD",
    "amount": 1000,
    "currency": "PEN",
    "finalAmount": 1000,
    "finalCurrency": "PEN",
    "country": "PEN",
    "createTime": "2022-03-01 17:53:18 GMT-08:00",
    "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
    ...  # other basic response fields
    "transferDetails": {
        "card": {
            "cardInfo": {
                "cardHolderName": "card_holder_name",
                "expirationMonth": 9,
                "expirationYear": 2024,
                "brand": "VISA",
                "bin": "458124",
                "last4": "0000"
            },
            "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237"
        }
    },
    "transferStatus": "SETTLED",
    "description": "this is a test pay",
    "subMerchantId": "UUID"
}

HTTP Headers Details

Key Value
Authorization "bearer" + " " + {{access_token}}
x-api-key {{api_key}}

PATH and Query Parameters

Parameter Type Description
idempotencyKey String The idempotency key of the authorization which need to capture

Request Body Parameters

Parameter Required Type Description
amount Long Captured amount. By default, it will be the total amount of the authorization. It can be equal or less but not be greater than the authorized amount.

Cancel An Authorization

HTTP Request

POST /v1/payments/charges/cancel/{{idempotencyKey}}

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Response
{
    "transferStatusCode": 200,
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "paymentMethod": "CREDIT_CARD",
    "amount": 1000,
    "currency": "PEN",
    "finalAmount": 1000,
    "finalCurrency": "PEN",
    "country": "PE",
    "createTime": "2022-03-01 17:53:18 GMT-08:00",
    "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
    ...  # other basic response fields
    "transferDetails": {
        "card": {
            "cardInfo": {
                "cardHolderName": "card_holder_name",
                "expirationMonth": 9,
                "expirationYear": 2024,
                "brand": "VISA",
                "bin": "458124",
                "last4": "0000"
            },
            "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237"
        }
    },
    "transferStatus": "CANCELLED",
    "description": "this is a test pay",
    "subMerchantId": "UUID"
}

PATH and Query Parameters

Parameter Type Description
idempotencyKey String The idempotency key of the authorization which need to cancel
Back to top