Payments

This request is a bundled, authorization and capture. Some processors require a payment transaction instead of using separate (authorization and capture) requests.

Payment

POST /v1/payments/

curl –X POST 'https://api.firstoken.co/v1/payments/' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR API KEY' \
--data-raw '{
    "transaction_info": {
        "type": "payment",
        "reference_code": "123456789"
    },
    "card":{
        "number": "4111111111111111"
        "expiration_date": "01/2024",
        "security_code": "838"
    },
    "order_info": {
        "amount_details": {
            "total_amount": 1000,
            "currency": "COP"
        }
    },
    "bill_to": {
        "first_name": "John",
        "last_name": "Doe",
        "country": "US",
        "address_1": "1 Market St",
        "address_2": "Suite 200",
        "city": "san francisco",
        "state": "CA",
        "phone_number": "4158880000",
        "email": "[e-mail]",
        "postal_code": "94105"
    },
    "device_info": {
        "ip_address": "12.7.8.120"
    }
}'

Payment with permanent token

POST /v1/payments/

curl –X POST 'https://api.firstoken.co/v1/payments/' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR API KEY' \
--data-raw '{
    "transaction_info": {
        "type": "payment",
        "reference_code": "123456789"
    },
    "card": {
        "number": "{{ 0beb9110-45d6-4df1-9d61-6b8081cd83b2 : detokenize }}",
        "expiration_date": "{{ 0beb9110-45d6-4df1-9d61-6b8081cd83b2 : detokenize }}",
        "security_code": "208"
    },
    "order_info": {
        "amount_details": {
            "total_amount": 1000,
            "currency": "COP"
        }
    },
    "bill_to": {
        "first_name": "John",
        "last_name": "Doe",
        "country": "US",
        "address_1": "1 Market St",
        "address_2": "Suite 200",
        "city": "san francisco",
        "state": "CA",
        "phone_number": "4158880000",
        "email": "[e-mail]",
        "postal_code": "94105"
    },
    "device_info": {
        "ip_address": "12.7.8.120"
    }
}'

Payment with temporal token

POST /v1/payments/

curl –X POST 'https://api.firstoken.co/v1/payments/' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR API KEY' \
--data-raw '{
    "transaction_info": {
        "type": "payment",
        "reference_code": "123456789"
    },
    "card": {
        "number": "{{ fa5f200d-2c48-41a5-a4c8-b4ec27819868 : transaction }}",
        "expiration_date": "{{ fa5f200d-2c48-41a5-a4c8-b4ec27819868 : transaction }}",
        "security_code": "{{ fa5f200d-2c48-41a5-a4c8-b4ec27819868 : transaction }}"
    },
    "order_info": {
        "amount_details": {
            "total_amount": 1000,
            "currency": "COP"
        }
    },
    "bill_to": {
        "first_name": "John",
        "last_name": "Doe",
        "country": "US",
        "address_1": "1 Market St",
        "address_2": "Suite 200",
        "city": "san francisco",
        "state": "CA",
        "phone_number": "4158880000",
        "email": "[e-mail]",
        "postal_code": "94105"
    },
    "device_info": {
        "ip_address": "12.7.8.120"
    }
}'

Payment with both tokens

POST /v1/payments/

curl –X POST 'https://api.firstoken.co/v1/payments/' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR API KEY' \
--data-raw '{
    "transaction_info": {
        "type": "payment",
        "reference_code": "123456789"
    },
    "card": {
        "number": "{{ 0beb9110-45d6-4df1-9d61-6b8081cd83b2 : detokenize }}",
        "expiration_date": "{{ 0beb9110-45d6-4df1-9d61-6b8081cd83b2 : detokenize }}",
        "security_code": "{{ fa5f200d-2c48-41a5-a4c8-b4ec27819868 : transaction }}"
    },
    "order_info": {
        "amount_details": {
            "total_amount": 1000,
            "currency": "COP"
        }
    },
    "bill_to": {
        "first_name": "John",
        "last_name": "Doe",
        "country": "US",
        "address_1": "1 Market St",
        "address_2": "Suite 200",
        "city": "san francisco",
        "state": "CA",
        "phone_number": "4158880000",
        "email": "[e-mail]",
        "postal_code": "94105"
    },
    "device_info": {
        "ip_address": "12.7.8.120"
    }
}'

With these endpoint we can get the following response

Example of the JSON response

{
    "status": "success",
    "message": "Payment sucessful",
    "data": {
        "transaction_info": {
            "type": "payment_response",
            "reference_code": "123456789",
            "transaction_id": "0001708984029002777379",
            "request_id": "7089840305786411604953",
            "status": "Authorized",
            "response_code": "00",
            "reconciliation_id": "7089840305786411604953",
            "created_at": "2024-02-26T21:47:11Z"
        },
        "order_info": {
            "amount_details": {
                "authorized_amount": 1000,
                "currency": "COP"
            }
        },
        "processor_info": {
            "approval_code": "831000",
            "transaction_id": "016153570198200",
            "avs": {
                "code": "Y",
                "codeRaw": "Y"
            }
        }
    }
}

Attributes of the response

status: string The status is a string result that only has two possible values. "Success, “Error” or "Fail".

message: string The message value represents a short description about the status code

data: {object} The value of the data represents a set of JSON objects with the transaction’s details:

• transaction_info: {object} The wrapper object of the transaction’s information. Contains:

  • type: string The type of transaction response.

  • reference_code: string

    A reference code for the transaction.

  • transaction_id: string

    Our transaction identifier of the request. It is used in other requests.

  • request_id: string

    The identifier of the request associated with the transaction.

  • status: string

    The status received of the transaction.

  • response_code: string

    The response code for the authorization.

  • reconciliation_id: string

    The response identifier for reconciliation logs.

  • created_at: ISO Date

    The ISO Date of the request.

• order_info: {object} The object for the order information sent it in the body request.

  • amount_details: {object} The total amount details, like total and currency.

• processor_info: {object} The object for the processor information response.

  • approval_code: string Authorization code. Returned only when the processor returns this value

  • transaction_id: string The processor transaction ID

  • avs: {object} Address Verification Service (AVS) is a service provided by the payment brands that determines the match or partial match of the consumer's address information.