Authorize and Charge Later
POST https://gateway-api.paycertify.com/api/transactions/auth
Default Behavior
In order to charge later, you need to make two requests: first an auth
request, which blocks balance on customer’s credit card, and then run capture
request, to flag the authorization for settlement.
Parameter | Type | Length | Presence | Description | Example |
---|---|---|---|---|---|
processor_id |
uuid |
36 | Optional[1] | The Processor record ID | 41f00869-d7b3-413e-9476-9ef1a8bc2f28 |
amount |
number |
0.01-9999999 | Required | Total transaction amount | 3.56 |
card_number |
string |
8-19 | Required | The credit card to charge | 411111111111111 |
card_expiry_month |
string |
2 | Required | The expiration month with two positions | 01 |
card_expiry_year |
string |
4 | Required | The expiration year with four positions | 2021 |
card_cvv |
string |
3-4 | Conditional[2] | 3 or 4 digit card verification code | 123 |
merchant_transaction_id |
string |
1-255 | Required | A merchant assigned identifier (your transaction ID) | my-order-id-0001 |
first_name |
string |
1-255 | Conditional[3] | Customer’s first name | John |
last_name |
string |
1-255 | Conditional[3] | Customer’s last name | Doe |
email |
string |
1-255 | Optional | Customer’s email | [email protected] |
mobile_phone |
string |
11-15 | Optional | Customer’s phone | 11231231234 |
street_address_1 |
string |
1-255 | Optional | Billing address first line (street address) | 59 N Santa Cruz Avenue |
street_address_2 |
string |
1-255 | Optional | Billing address second line (suite, apt, etc) | Suite M |
city |
string |
1-255 | Optional | Billing address city | Los Gatos |
state |
string |
3 | Optional | Billing address state abbreviation | CA |
country |
string |
2 | Optional | Billing address country abbreviation | US |
zip |
string |
2-255 | Optional | Billing address postal code | 95030 |
shipping_street_address_1 |
string |
1-255 | Optional | Shipping address first line (street address) | 59 N Santa Cruz Avenue |
shipping_street_address_2 |
string |
1-255 | Optional | Shipping address second line (suite, apt, etc) | Suite M |
shipping_city |
string |
1-255 | Optional | Shipping address city | Los Gatos |
shipping_state |
string |
3 | Optional | Shipping address state abbreviation | CA |
shipping_country |
string |
2 | Optional | Shipping address country abbreviation | US |
shipping_zip |
string |
2-255 | Optional | Shipping address postal code | 95030 |
ip_address |
string |
12 | Required | Customer’s IP address | 192.168.108.105 |
document_number |
string |
11-20 | Required[4] | The ID of the Identification document for the customer | 00003456790 |
capture |
boolean |
- | Optional[5] | Automatically capture Authorizations. Default: false | true |
meta |
json |
- | Optional | A fields’ list related to merchant’s business | “meta”: {} |
Parameter | Type | Length | Description | Example |
---|---|---|---|---|
transaction.id |
uuid |
36 | This transaction’s ID | 41f00869-d7b3-413e-9476-9ef1a8bc2f28 |
transaction.merchant_id |
uuid |
36 | The user’s merchant ID | 41f00869-d7b3-413e-9476-9ef1a8bc2f28 |
transaction.user_id |
uuid |
36 | The user’s ID | 41f00869-d7b3-413e-9476-9ef1a8bc2f28 |
transaction.processor_id |
uuid |
36 | The processor’s ID | 41f00869-d7b3-413e-9476-9ef1a8bc2f28 |
transaction.merchant_transaction_id |
string |
1-255 | The merchant assigned identifier | my-order-id-0001 |
transaction.updated_at |
datetime |
- | Last time this transaction was updated, on ISO 8601 UTC | 2018-02-16T16:33:40+00:00 |
transaction.created_at |
datetime |
- | Time that transaction was created, on ISO 8601 UTC | 2018-02-16T16:33:40+00:00 |
transaction.events.*.id |
uuid |
36 | This event’s ID | 41f00869-d7b3-413e-9476-9ef1a8bc2f28 |
transaction.events.*.success |
boolean |
- | If the event was a successful event or not | true |
transaction.events.*.event_type |
string |
4-10 | The type of event being performed | auth, capture, sale, void, refund |
transaction.events.*.amount |
number |
0.01-9999999 | Total event amount | 3.56 |
transaction.events.*.processor_code |
string |
2-10 | The processor response code | 00 |
transaction.events.*.processor_message |
string |
1-255 | A human readable message from the processor | APPROVAL V12341 |
transaction.events.*.processor_transaction_id |
string |
1-255 | A processor assigned identifier | 00000000143242 |
transaction.events.*.updated_at |
datetime |
- | Last time this event was updated, on ISO 8601 UTC | 2018-02-16T16:33:40+00:00 |
transaction.events.*.created_at |
datetime |
- | Time that event was created, on ISO 8601 UTC | 2018-02-16T16:33:40+00:00 |
All fields that are included on the authorization response are also echoed back.
curl --location --request POST 'https://gateway-api.paycertify.com/api/transactions/auth' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data-raw '{
"processor_id": PROCESSOR_ID,
"amount": "1.00",
"card_cvv": "999",
"card_number": "4111111111111111",
"card_expiry_month": "01",
"card_expiry_year": "2021",
"first_name": "John",
"last_name": "Doe",
"street_address_1": "59 N Santa Cruz Avenue",
"street_address_2": "Suite M",
"city": "Los Gatos",
"state":"CA",
"country": "US",
"ip_address": "127.0.0.1",
"dynamic_descripton": "MY-DESCRIPTOR",
"mobile_phone": "11231231234",
"document_number": "11112222",
"merchant_transaction_id": "my-order-id-0001",
"email": "[email protected]",
"zip": "95030",
"meta": {
"custom_field_1": "111111",
"custom_field_2": "11111"
}
}'
Responds with:
{
"transaction": {
"id": "a0b94138-a86e-4f04-a3e2-f62e689a25f9",
"merchant_id": "dc6cbdba-926b-4bbc-badc-4171eadcd07f",
"user_id": "f5487603-f130-4c5c-ab85-79b13a221169",
"processor_id": "fc4055c6-99c3-4de1-9947-40be598cb525",
"merchant_transaction_id": "my-order-id-0001",
"transaction_type": "card",
"first_name": "John",
"last_name": "Doe",
"street_address_1": "59 N Santa Cruz Avenue",
"street_address_2": "Suite M",
"city": "Los Gatos",
"state": "CA",
"country": "US",
"zip": "95030",
"email": "[email protected]",
"mobile_phone": "11231231234",
"checkout_url": null,
"meta": {
"custom_field_1": "111111",
"custom_field_2": "11111"
},
"updated_at": "2020-03-16T23:29:37+0000",
"created_at": "2020-03-16T23:29:37+0000",
"events": [
{
"id": "20ce16aa-d87a-4c52-b1db-9f74349b0c2d",
"success": true,
"status": "pending_settlement",
"threeds_response": null,
"avs_response": null,
"auth_code": "160854",
"cvv_response": null,
"event_type": "sale",
"amount": "1.00",
"ip_address": "127.0.0.1",
"processor_code": "00",
"processor_message": "Approved",
"processor_transaction_id": "975734874493625",
"processor_threeds_response": null,
"processor_avs_response": null,
"processor_cvv_response": null,
"processor_code_detail": "Approved",
"batch_id": null,
"updated_at": "2020-03-16T23:29:38+0000",
"created_at": "2020-03-16T23:29:37+0000"
}
],
"card_number": "411111******1111",
"card_brand": "visa",
"card_expiry_month": "01",
"card_expiry_year": "2021"
}
}
POST https://gateway-api.paycertify.com/api/transactions/{transaction_id}/capture
After running the auth transaction event, you should be able to capture the funds. Use the transaction ID sent back in the response to capture the desired amount.
Parameter | Type | Length | Presence | Description | Example |
---|---|---|---|---|---|
amount |
number |
0.01-9999999 | Required | Total transaction amount | 3.56 |
Parameter | Type | Length | Description | Example |
---|---|---|---|---|
transaction.id |
uuid |
36 | This transaction’s ID | 41f00869-d7b3-413e-9476-9ef1a8bc2f28 |
transaction.merchant_id |
uuid |
36 | The user’s merchant ID | 41f00869-d7b3-413e-9476-9ef1a8bc2f28 |
transaction.user_id |
uuid |
36 | The user’s ID | 41f00869-d7b3-413e-9476-9ef1a8bc2f28 |
transaction.processor_id |
uuid |
36 | The processor’s ID | 41f00869-d7b3-413e-9476-9ef1a8bc2f28 |
transaction.merchant_transaction_id |
string |
1-255 | The merchant assigned identifier | my-order-id-0001 |
transaction.updated_at |
datetime |
- | Last time this transaction was updated, on ISO 8601 UTC | 2018-02-16T16:33:40+00:00 |
transaction.created_at |
datetime |
- | Time that transaction was created, on ISO 8601 UTC | 2018-02-16T16:33:40+00:00 |
transaction.events.*.id |
uuid |
36 | This event’s ID | 41f00869-d7b3-413e-9476-9ef1a8bc2f28 |
transaction.events.*.success |
boolean |
- | If the event was a successful event or not | true |
transaction.events.*.event_type |
string |
4-10 | The type of event being performed | auth, capture, sale, void, refund |
transaction.events.*.amount |
number |
0.01-9999999 | Total event amount | 3.56 |
transaction.events.*.processor_code |
string |
2-10 | The processor response code | 00 |
transaction.events.*.processor_message |
string |
1-255 | A human readable message from the processor | APPROVAL V12341 |
transaction.events.*.processor_transaction_id |
string |
1-255 | A processor assigned identifier | 00000000143242 |
transaction.events.*.updated_at |
datetime |
- | Last time this event was updated, on ISO 8601 UTC | 2018-02-16T16:33:40+00:00 |
transaction.events.*.created_at |
datetime |
- | Time that event was created, on ISO 8601 UTC | 2018-02-16T16:33:40+00:00 |
curl --request POST \
--url https://gateway-api.paycertify.com/api/transactions/{transaction_id}/capture \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--form 'amount=0.50'
Responds with:
{
"transaction": {
"id": "3410596f-d596-42d4-9811-41d43868e984",
"merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
"user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
"processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
"merchant_transaction_id": "my-order-id-0001",
"card_number": "411111******1111",
"card_brand": "visa",
"card_expiry_month": "01",
"card_expiry_year": "2021",
"first_name": "John",
"last_name": "Doe",
"street_address_1": "59 N Santa Cruz Avenue",
"street_address_2": "Suite M",
"city": "Los Gatos",
"state": "CA",
"country": "US",
"zip": "95030",
"email": "[email protected]",
"mobile_phone": "+11231231234",
"updated_at": "2018-02-16T16:33:40+00:00",
"created_at": "2018-02-16T16:33:39+00:00",
"events": [
{
"id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
"success": true,
"threeds_response": null,
"avs_response": null,
"event_type": "capture",
"amount": "0.50",
"ip_address": "127.0.0.1",
"processor_code": "00",
"processor_message": "APPROVAL TAS123 ",
"processor_transaction_id": "000000000252618",
"processor_threeds_response": null,
"processor_avs_response": "0",
"updated_at": "2018-02-16T16:35:40+00:00",
"created_at": "2018-02-16T16:35:39+00:00"
}
{
"id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
"success": true,
"threeds_response": null,
"avs_response": null,
"event_type": "auth",
"amount": "1.00",
"ip_address": "127.0.0.1",
"processor_code": "00",
"processor_message": "APPROVAL TAS656 ",
"processor_transaction_id": "000000000252616",
"processor_threeds_response": null,
"processor_avs_response": "0",
"updated_at": "2018-02-16T16:33:40+00:00",
"created_at": "2018-02-16T16:33:39+00:00"
}
]
}
}
Auto Capture[5]
If your processor is configured with the Auto Capture feature, you may call an auth
or sale
request with a capture=false
flag. The transactions will be automatically captured by gateway up to 24h.
curl --location --request POST 'https://gateway-api.paycertify.com/api/transactions/sale' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data-raw '{
"processor_id": PROCESSOR_ID,
"amount": "1.00",
"capture": "false",
"card_cvv": "999",
"card_number": "4111111111111111",
"card_expiry_month": "01",
"card_expiry_year": "2021",
"first_name": "John",
"last_name": "Doe",
"street_address_1": "59 N Santa Cruz Avenue",
"street_address_2": "Suite M",
"city": "Los Gatos",
"state":"CA",
"country": "CL",
"ip_address": "127.0.0.1",
"dynamic_descripton": "MY-DESCRIPTOR",
"mobile_phone": "11231231234",
"document_number": "33996438",
"merchant_transaction_id": "my-order-id-0001",
"email": "[email protected]",
"zip": "95030",
"meta": {
"custom_field_1": "111111",
"custom_field_2": "11111"
}
}'
Responds with:
{
"transaction": {
"id": "a0b94138-a86e-4f04-a3e2-f62e689a25f9",
"merchant_id": "dc6cbdba-926b-4bbc-badc-4171eadcd07f",
"user_id": "f5487603-f130-4c5c-ab85-79b13a221169",
"processor_id": "fc4055c6-99c3-4de1-9947-40be598cb525",
"merchant_transaction_id": "my-order-id-0001",
"transaction_type": "card",
"first_name": "John",
"last_name": "Doe",
"street_address_1": "59 N Santa Cruz Avenue",
"street_address_2": "Suite M",
"city": "Los Gatos",
"state": "CA",
"country": "US",
"zip": "95030",
"email": "[email protected]",
"mobile_phone": "11231231234",
"checkout_url": null,
"meta": {
"custom_field_1": "111111",
"custom_field_2": "11111"
},
"updated_at": "2020-03-16T23:29:37+0000",
"created_at": "2020-03-16T23:29:37+0000",
"events": [
{
"id": "20ce16aa-d87a-4c52-b1db-9f74349b0c2d",
"success": true,
"status": "pending_settlement",
"threeds_response": null,
"avs_response": null,
"auth_code": "160854",
"cvv_response": null,
"event_type": "auth",
"amount": "1.00",
"ip_address": "127.0.0.1",
"processor_code": "00",
"processor_message": "Approved",
"processor_transaction_id": "975734874493625",
"processor_threeds_response": null,
"processor_avs_response": null,
"processor_cvv_response": null,
"processor_code_detail": "Approved",
"batch_id": null,
"updated_at": "2020-03-16T23:29:38+0000",
"created_at": "2020-03-16T23:29:37+0000"
}
],
"card_number": "411111******1111",
"card_brand": "visa",
"card_expiry_month": "01",
"card_expiry_year": "2021",
"capture": false
}
}
[1] if processor_id
has not been provided, the gateway will pick one randomly.
[2] card_cvv
is a not required as a default. There are some processors such as “Payvision” that requires this field to be present on VISA, MASTER, AMEX.
[3] first_name
and last_name
are required and minimum of 2 chars when running transactions with Skrill Card processor.
[4] Only required to PayVisionCard processor. The document ID is the official according to the Country. Examples: CPF, CNPJ, RUT.
[5] If the Auto-capture feature is enabled for the processor, authorized transactions will be captured automatically up to 24h.