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
1
$ curl -X POST \
2
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
-H 'X-Login: sak223k2wdksdl2' \
4
-H 'X-Trans-Key: fm12O7G9' \
5
-H 'X-Version: 2.1' \
6
-H 'User-Agent: MerchantTest / 1.0 ' \
7
-H 'Content-Type: application/json' \
8
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
9
-d '{body}'
10
https://api.dlocal.com/secure_payments
Copied!
1
{
2
"amount": 120,
3
"currency" : "USD",
4
"country": "BR",
5
"payment_method_id" : "CARD",
6
"payment_method_flow" : "DIRECT",
7
"payer":{
8
"name" : "Thiago Gabriel",
9
"email" : "[email protected]",
10
"document" : "53033315550"
11
},
12
"card":{
13
"holder_name" : "Thiago Gabriel",
14
"number" : "4111111111111111",
15
"cvv" : "123",
16
"expiration_month" : 10,
17
"expiration_year" : 2040,
18
"capture" : "false"
19
},
20
"order_id": "657434343",
21
"notification_url": "http://merchant.com/notifications"
22
}
Copied!
1
{
2
"id": "D-4-e2227981-8ec8-48fd-8e9a-19fedb08d73a",
3
"amount": 120,
4
"currency": "USD",
5
"payment_method_id": "CARD",
6
"payment_method_type": "CARD",
7
"payment_method_flow": "DIRECT",
8
"country": "BR",
9
"card": {
10
"holder_name": "Thiago Gabriel",
11
"expiration_month": 10,
12
"expiration_year": 2040,
13
"brand": "VI",
14
"last4": "1111"
15
},
16
"created_date": "2019-02-06T21:04:43.000+0000",
17
"approved_date": "2019-02-06T21:04:44.000+0000",
18
"status": "AUTHORIZED",
19
"status_detail": "The payment was authorized",
20
"status_code": "600",
21
"order_id": "657434343",
22
"notification_url": "http://merchant.com/notifications"
23
}
Copied!
The id returned corresponds to the unique identifier of the Authorization (authorization_id)

Capture an Authorization

post
https://api.dlocal.com
/payments
Capture an Authorization

Example Capture

Example Capture Request
Example Capture Response
1
$ curl -X POST \
2
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
-H 'X-Login: sak223k2wdksdl2' \
4
-H 'X-Trans-Key: fm12O7G9' \
5
-H 'X-Version: 2.1' \
6
-H 'User-Agent: MerchantTest / 1.0 ' \
7
-H 'Content-Type: application/json' \
8
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
9
-d '{body}'
10
https://api.dlocal.com/payments
Copied!
1
{
2
"authorization_id": "D-4-e2227981-8ec8-48fd-8e9a-19fedb08d73a",
3
"amount": 120,
4
"currency": "USD",
5
"order_id": "657434343-1"
6
}
Copied!
1
{
2
"id": "D-4-09f52dd0-5cfa-4b0e-a471-1608ea0dba24",
3
"amount": 120,
4
"currency": "USD",
5
"country": "BR",
6
"created_date": "2019-02-07T13:47:06.000+0000",
7
"approved_date": "2019-02-07T13:47:06.000+0000",
8
"status": "PAID",
9
"status_detail": "The payment was paid",
10
"status_code": "200",
11
"order_id": "657434343-1",
12
"authorization_id": "D-4-e2227981-8ec8-48fd-8e9a-19fedb08d73a"
13
}
Copied!
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

An authorization can be cancelled before it is captured if the payment is no longer needed.
post
https://api.dlocal.com/payments/
{authorization_id}/cancel
Cancel an Authorization

Example Cancel

Example Cancel Request
Example Cancel Response
1
$ curl -X POST \
2
-H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
-H 'X-Login: sak223k2wdksdl2' \
4
-H 'X-Trans-Key: fm12O7G9' \
5
-H 'X-Version: 2.1' \
6
-H 'User-Agent: MerchantTest / 1.0 ' \
7
-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
8
https://api.dlocal.com/payments/D-4-09f52dd0-5cfa-4b0e-a471-1608ea0dba24/cancel
Copied!
1
{
2
"id": "D-4-09f52dd0-5cfa-4b0e-a471-1608ea0dba24",
3
"amount": 120,
4
"currency": "USD",
5
"payment_method_id": "CARD",
6
"payment_method_type": "CARD",
7
"payment_method_flow": "DIRECT",
8
"country": "BR",
9
"created_date": "2019-02-07T17:37:36.000+0000",
10
"approved_date": "2019-02-07T17:37:36.000+0000",
11
"status": "CANCELLED",
12
"status_detail": "The payment was cancelled",
13
"status_code": "400",
14
"order_id": "be2fbac6-6114-44dc-a5f5-c4cdc38dda57",
15
"notification_url": "http://conductor.sandbox.internal/robot-server/rest/generic/notification/new"
16
}
Copied!

$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:
Request Example
Response Example
Request example:
1
{
2
"amount": 0,
3
"currency": "BRL",
4
"country": "BR",
5
"payment_method_id": "CARD",
6
"payment_method_flow": "DIRECT",
7
"payer": {
8
"name": "MXFGpBEw AJsGTALt",
9
"email": "[email protected]",
10
"phone": "4832695335",
11
"address": {
12
"country": "BR",
13
"state": "Santa Catarina",
14
"city": "Florianopolis",
15
"zip_code": "88058",
16
"street": "Rodovia Armando Calil Bulos",
17
"number": "5940"
18
},
19
"document": 26410722
20
},
21
"card": {
22
"holder_name" : "Thiago Gabriel",
23
"expiration_month": 7,
24
"expiration_year": 2024,
25
"brand": "Visa",
26
"verify": true,
27
"capture": false,
28
"cvv": "***",
29
"number": "42976**********"
30
},
31
"order_id": "BENtest-h8fJ8blUTjY",
32
"description": "LO4nLkTqt2tt",
33
"notification_url": "https://postman-echo.com/post"
34
}
Copied!
Response Example:
1
{
2
"id": "T-40004-eebc14d9-8381-4bf6-b8b7-82acbb06f166",
3
"amount": 0,
4
"currency": "BRL",
5
"payment_method_id": "CARD",
6
"payment_method_type": "CARD",
7
"payment_method_flow": "DIRECT",
8
"country": "BR",
9
"card": {
10
"holder_name" : "Thiago Gabriel",
11
"expiration_month": 7,
12
"expiration_year": 2024,
13
"brand": "VI",
14
"last4": "8528",
15
"verify": true
16
},
17
"created_date": "2020-09-29T17:42:40.000+0000",
18
"approved_date": "2020-09-29T17:42:40.000+0000",
19
"status": "VERIFIED",
20
"status_detail": "The payment was verified.",
21
"status_code": "700",
22
"order_id": "BENtest-h8fJ8blU",
23
"description": "LO4nLkTqt2tt",
24
"notification_url": "https://postman-echo.com/post",
25
}
Copied!

Refunds for Captures

Refunds are applied to the Captures, not the Authorization.
post
https://api.dlocal.com/
refunds
Make a Refund
Read more about Refunds here.
Last modified 6mo ago