> For the complete documentation index, see [llms.txt](https://firstoken.gitbook.io/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://firstoken.gitbook.io/api-docs/api-reference/payments/endpoints/authorizations.md).

# 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

<details>

<summary>Simple Authorization</summary>

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

{% code title="POST /v1/payments/" %}

```json
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": "test@cybs.com",
        "postal_code": "94105"
    },
    "device_info": {
        "ip_address": "12.7.8.120"
    }
}'
```

{% endcode %}

</details>

<details>

<summary>Authorization with Permanent Token</summary>

You can use any valid permanent token in your vault. The request will receive and detokenize a token.

{% code title="POST /v1/payments/" %}

```json
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": "test@cybs.com",
        "postal_code": "94105"
    },
    "device_info": {
        "ip_address": "12.7.8.120"
    }
}'
```

{% endcode %}

</details>

<details>

<summary>Authorization with Temporal token</summary>

You can use any valid temporal token created with our other APIs. The request will receive and detokenize a token.

{% code title="POST /v1/payments/" %}

```json
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": "test@cybs.com",
        "postal_code": "94105"
    },
    "device_info": {
        "ip_address": "12.7.8.120"
    }
}'
```

{% endcode %}

</details>

<details>

<summary>Authorization with both tokens</summary>

You can use permanent token and temporal token in the same request. The request will receive and detokenize both tokens.

{% code title="POST /v1/payments/" %}

```json
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": "test@cybs.com",
        "postal_code": "94105"
    },
    "device_info": {
        "ip_address": "12.7.8.120"
    }
}'
```

{% endcode %}

</details>

With these endpoints we can get the following response

{% tabs %}
{% tab title="Example of the response" %}

```json
{
    "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"
            }
        }
    }
}
```

{% endtab %}

{% tab title="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.&#x20;
> * **processor\_info**: {*object*} \
>   The object for the processor information response.&#x20;
>   * **approval\_code**: *string* \
>     Authorization code. Returned only when the processor returns this value&#x20;
>   * **transaction\_id**: *string* \
>     The processor transaction ID&#x20;
>   * **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.
>     {% endtab %}
>     {% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://firstoken.gitbook.io/api-docs/api-reference/payments/endpoints/authorizations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.