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 or booking car rentals.

How does it work

It's a two-step process. First, you need to create an Authorization, and then you need to Capture it.

Create an authorization

To create an authorization, simply create a regular card payment with the parameter capture = FALSE within the card object.

Example

$ curl -X POST \
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
    -H 'X-Login: sak223k2wdksdl2' \
    -H 'X-Trans-Key: fm12O7G9' \
    -H 'X-Version: 2.1' \
    -H 'User-Agent: MerchantTest / 1.0 ' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
    -d '{body}'
    https://api.dlocal.com/secure_payments

{
    "amount": 120,
    "currency" : "USD",
    "country": "BR",
    "payment_method_id" : "CARD",
    "payment_method_flow" : "DIRECT",
    "payer":{
        "name" : "Thiago Gabriel",
        "email" : "[email protected]",
        "document" : "53033315550"
    },
    "card":{
        "holder_name" : "Thiago Gabriel",
        "number" : "4111111111111111",
        "cvv" : "123",
        "expiration_month" : 10,
        "expiration_year" : 2040,
        "capture" : "false"
    },
    "order_id": "657434343",
    "notification_url": "http://merchant.com/notifications"
}

{
    "id": "D-4-e2227981-8ec8-48fd-8e9a-19fedb08d73a",
    "amount": 120,
    "currency": "USD",
    "payment_method_id": "CARD",
    "payment_method_type": "CARD",
    "payment_method_flow": "DIRECT",
    "country": "BR",
    "card": {
        "holder_name": "Thiago Gabriel",
        "expiration_month": 10,
        "expiration_year": 2040,
        "brand": "VI",
        "last4": "1111"
    },
    "created_date": "2019-02-06T21:04:43.000+0000",
    "approved_date": "2019-02-06T21:04:44.000+0000",
    "status": "AUTHORIZED",
    "status_detail": "The payment was authorized",
    "status_code": "600",
    "order_id": "657434343",
    "notification_url": "http://merchant.com/notifications"
}

The id returned corresponds to the unique identifier of the Authorization (authorization_id).

Capture an authorization

Example

$ curl -X POST \
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
    -H 'X-Login: sak223k2wdksdl2' \
    -H 'X-Trans-Key: fm12O7G9' \
    -H 'X-Version: 2.1' \
    -H 'User-Agent: MerchantTest / 1.0 ' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
    -d '{body}'
    https://api.dlocal.com/payments

{
    "authorization_id": "D-4-e2227981-8ec8-48fd-8e9a-19fedb08d73a",
    "amount": 120,
    "currency": "USD",
    "order_id": "657434343-1"
}

{
    "id": "D-4-09f52dd0-5cfa-4b0e-a471-1608ea0dba24",
    "amount": 120,
    "currency": "USD",
    "country": "BR",
    "created_date": "2019-02-07T13:47:06.000+0000",
    "approved_date": "2019-02-07T13:47:06.000+0000",
    "status": "PAID",
    "status_detail": "The payment was paid",
    "status_code": "200",
    "order_id": "657434343-1",
    "authorization_id": "D-4-e2227981-8ec8-48fd-8e9a-19fedb08d73a"
}

Parameter details

Body

Property	Type	Description
`authorization_id`*	string	ID of the Authorization to be captured.
`amount`*	number	Amount to be captured (in the `currency` specified in currency). Must be equal to or less than the authorized amount. If not included, the capture will be for the total amount of the authorization.
`currency`	string	Transaction currency in ISO 4217. Each country accepts USD and local currency. Required if amount is present.
`order_id`	string	ID of the capture given by the merchant in their system. Think of it as an external id of the capture.

Required

Authorization Cancellation

Authorization can be canceled before it is captured if the payment is no longer needed.

Example

$ curl -X POST \
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
    -H 'X-Login: sak223k2wdksdl2' \
    -H 'X-Trans-Key: fm12O7G9' \
    -H 'X-Version: 2.1' \
    -H 'User-Agent: MerchantTest / 1.0 ' \
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
    https://api.dlocal.com/payments/D-4-09f52dd0-5cfa-4b0e-a471-1608ea0dba24/cancel

{
    "id": "D-4-09f52dd0-5cfa-4b0e-a471-1608ea0dba24",
    "amount": 120,
    "currency": "USD",
    "payment_method_id": "CARD",
    "payment_method_type": "CARD",
    "payment_method_flow": "DIRECT",
    "country": "BR",
    "created_date": "2019-02-07T17:37:36.000+0000",
    "approved_date": "2019-02-07T17:37:36.000+0000",
    "status": "CANCELLED",
    "status_detail": "The payment was cancelled",
    "status_code": "400",
    "order_id": "be2fbac6-6114-44dc-a5f5-c4cdc38dda57",
    "notification_url": "http://conductor.sandbox.internal/robot-server/rest/generic/notification/new"
}

Parameter details

Path

Property	Type	Description
`authorization_id`*	string	The Authorization ID.

Required

$0 Authorization

Use a $0 Authorization to validate the user's card. You need to create an Authorization as explained above, but with amount = 0 and verify = true within the card object:

{
    "amount": 0,
    "currency": "BRL",
    "country": "BR",
    "payment_method_id": "CARD",
    "payment_method_flow": "DIRECT",
    "payer": {
        "name": "MXFGpBEw AJsGTALt",
        "email": "[email protected]",
        "phone": "4832695335",
        "address": {
            "country": "BR",
            "state": "Santa Catarina",
            "city": "Florianopolis",
            "zip_code": "88058",
            "street": "Rodovia Armando Calil Bulos",
            "number": "5940"
        },
        "document": 26410722
    },
    "card": {
        "holder_name" : "Thiago Gabriel",
        "expiration_month": 7,
        "expiration_year": 2024,
        "brand": "Visa",
        "verify": true,
        "capture": false,
        "cvv": "***",
        "number": "42976**********"
    },
    "order_id": "BENtest-h8fJ8blUTjY",
    "description": "LO4nLkTqt2tt",
    "notification_url": "https://postman-echo.com/post"
}

{
    "id": "T-40004-eebc14d9-8381-4bf6-b8b7-82acbb06f166",
    "amount": 0,
    "currency": "BRL",
    "payment_method_id": "CARD",
    "payment_method_type": "CARD",
    "payment_method_flow": "DIRECT",
    "country": "BR",
    "card": {
        "holder_name" : "Thiago Gabriel",
        "expiration_month": 7,
        "expiration_year": 2024,
        "brand": "VI",
        "last4": "8528",
        "verify": true
    },
    "created_date": "2020-09-29T17:42:40.000+0000",
    "approved_date": "2020-09-29T17:42:40.000+0000",
    "status": "VERIFIED",
    "status_detail": "The payment was verified.",
    "status_code": "700",
    "order_id": "BENtest-h8fJ8blU",
    "description": "LO4nLkTqt2tt",
    "notification_url": "https://postman-echo.com/post",
}

Refunds for captures

Refunds are applied to the Captures, not the Authorization.

Make a refund

On the payment_id parameter, make sure to include the id of the Capture, not the Authorization.

Parameter details

Body

Property	Type	Description
`paymeny_id`*	string	The ID of the capture.
`notification_url`*	string	If a refund is `PENDING`, the refund confirmation is sent asynchronously to this URL.
`amount`*	number	Amount to refund. If the amount is empty, then the default is the total amount of the payment. Required if `currency` is present.
`currency`	string	Transaction currency in ISO 4217. Each country accepts USD and local currency. Required if amount is present.
`description`	string	Description of the refund.

Required

Example

{
   "id" : "REF42342",
   "payment_id" : "D-4-09f52dd0-5cfa-4b0e-a471-1608ea0dba24",
   "notification_url" : "http://some.url",
   "amount" : 803.04,
   "currency" : "BRL",
   "status" : "SUCCESS",
   "status_code" : 200,
   "status_detail" : "The refund was paid",
   "created_date" : "2018-09-06T22:03:03.000+0000",
   "amount_refunded" : 803.04
}