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[4]

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.