Authorization and Capture

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.

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 Authorization

Example Authorization Request
Example Authorization Response
$ 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" : "thiago@example.com",
"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

post
Capture an Authorization

https://api.dlocal.com/payments
Request
Response
Body Parameters
authorization_id
required
string
ID of the Authorization to be captured.
amount
optional
number
Amount to be captured (in the currency specified in currency). Must be equal or less than the authorized amount. If not included, the captured will be for the total amount of the authorization.
currency
optional
string
Transaction currency in ISO 4217 (see http://en.wikipedia.org/wiki/ISO_4217). Each country accepts USD and local currency. Required if amount is present.
order_id
optional
string
ID of the capture given by the merchant in their system. Think of it as an external id of the capture.
200: OK
{
"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"
}

Example Capture

Example Capture Request
Example Capture Response
$ 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"
}

The id returned corresponds to the unique identifier of the Captured payment. Some countries allow multiple partial captures per Authorization. Contact your Technical Account Manager for more details.

Authorization Cancellation

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

post
Cancel an Authorization

https://api.dlocal.com/payments/{authorization_id}/cancel
Request
Response
Path Parameters
authorization_id
required
string
The Authorization id
200: OK
{
"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"
}

Example Cancel

Example Cancel Request
Example Cancel Response
$ 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"
}

Refunds for Captures

Refunds are applied to the Captures, not the Authorization.

post
Make a Refund

https://api.dlocal.com/refunds
On thepayment_id parameter, make sure to include the id of the Capture, not the Authorization.
Request
Response
Body Parameters
payment_id
required
string
The id of the capture.
notification_url
required
string
If a refund is pending, the refund confirmation is sent asynchronously to this URL.
amount
optional
number
Amount to refund. If the amount is empty, then the default is total amount of the payment. Required if currency is present.
currency
optional
string
Currency of the Amount. Required if amount is present.
description
optional
string
Description of the refund.
200: OK
{
"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
}

Read more about Refunds here.