Authorizations

Authorizations are used to authorize a payment to be charged with a specific amount at the target gateway. An authorization confirms that a payment card account holds enough funds to pay for a purchase. In this requests no funds are taken and if you wish to move the funds, you have to make a capture transaction after an authorization.

You can use these endpoints with your card information or using our tokens as explained below

Simple Authorization

You can use any valid credit card. The request receives a credit card number and other additional objects via attributes.

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": "authorization",
        "reference_code": "123456789"
    },
    "card": {
        "number": "4111111111111111",
        "expiration_date": "01/2024",
        "security_code": "001"
    },
    "order_info": {
        "amount_details": {
            "total_amount": 100,
            "currency": "COP"
        },
        "installments": 1
    },
    "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"
    }
}'

Authorization with Permanent Token

You can use any valid permanent token in your vault. The request will receive and detokenize a 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": "authorization",
        "reference_code": "123456789"
    },
    "card": {
        "number": "{{4242420428544242:detokenize}}",
        "expiration_date": "{{4242420428544242:detokenize}}",
        "security_code": "208"
    },
    "order_info": {
        "amount_details": {
            "total_amount": 100,
            "currency": "COP"
        },
        "installments": 1
    },
    "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"
    }
}'

Authorization with Temporal token

You can use any valid temporal token created with our other APIs. The request will receive and detokenize a 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": "authorization",
        "reference_code": "123456789"
    },
    "card": {
        "number": "{{ c32db413-0c2f-4bdc-ad37-d183ce15f3a7 : transaction }}",
        "expiration_date": "{{ c32db413-0c2f-4bdc-ad37-d183ce15f3a7 : transaction }}",
        "security_code": "{{ c32db413-0c2f-4bdc-ad37-d183ce15f3a7: transaction }}"
    },
    "order_info": {
        "amount_details": {
            "total_amount": 100,
            "currency": "COP"
        },
        "installments": 1
    },
    "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"
    }
}'

Authorization with both tokens

You can use permanent token and temporal token in the same request. The request will receive and detokenize 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": "authorization",
        "reference_code": "123456789"
    },
    "card": {
        "number": "{{ 4242420428544242 : detokenize }}",
        "expiration_date": "{{ 4242420428544242 : detokenize }}",
        "security_code": "{{ c32db413-0c2f-4bdc-ad37-d183ce15f3a7 : transaction }}"
    },
    "order_info": {
        "amount_details": {
            "total_amount": 100,
            "currency": "COP"
        },
        "installments": 1
    },
    "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 endpoints we can get the following response

Example of the response

{
    "status": "success",
    "message": "Authorization successful",
    "data": {
        "transaction_info": {
            "type": "authorization_response",
            "reference_code": "123456789",
            "transaction_id": "0001708977291937048626",
            "request_id": "7089772934086747504951",
            "status": "Authorized",
            "response_code": "00",
            "reconciliation_id": "7089772934086747504951",
            "created_at": "2024-02-26T19:54:54Z"
        },
        "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