PayCertify Docs

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.

Example

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.

Authorize and Charge Later

Default Behavior

Auto Capture[4]

Auto Capture^[4]