# Authorization ### Overview The Authorization endpoint authorizes a payment without capturing it. This is useful when you need to verify funds availability or when the final amount might change before capture. The funds are held on the customer's card but not yet collected. **POST** `/v1/payments/` ### What Happens Internally ``` Client Request → Firstoken API → [Tokenization + Authorization] → Response ``` 1. **Tokenization**: Card data is securely tokenized 2. **Authorization**: Payment is authorized and funds are held 3. **Response**: Authorization details returned (capture required separately) ### Request Body The request format is identical to the Payment endpoint, but with `"type": "authorization"` instead of `"type": "payment"`. #### Minimal Required Fields ```json { "transaction_info": { "type": "authorization", "reference_code": "1753550023570" }, "card": { "number": "4225289837059229", "expiration_date": "01/2030", "security_code": "123", "holder": "John Doe Jones" }, "order_info": { "amount_details": { "total_amount": 1000, "currency": "BRL", "items_amount": 1000 }, "installments": 1, "descriptor": "Test Payment" }, "cardholder_info": { "first_name": "John", "last_name": "Doe", "document": { "type": "CPF", "number": "54672396002", "nationality": "BR" }, "country": "BR", "address_1": "123 Main St", "city": "Sao Paulo", "state": "SP", "postal_code": "04001-000", "email": "john_autoaccept@test.com", "phone_number": "4158880000", "phone_type": "Mobile", "phone_area_code": "22" }, "bill_to": { "id": "1234567890", "first_name": "John", "last_name": "Doe", "document": { "type": "CPF", "number": "54672396002", "nationality": "BR" }, "country": "BR", "address_1": "123 Main St", "city": "Sao Paulo", "state": "SP", "postal_code": "04001-000", "email": "test@cybs.com", "phone_number": "4158880000", "phone_type": "Mobile", "phone_area_code": "22", "profile": "1" }, "line_items": [ { "category": { "id": "1", "name": "Category 1" }, "id": "1", "name": "Item 1", "price": 1500, "quantity": 1, "type": "Generic" } ], "device_info": { "ip_address": "127.0.0.1", "fingerprint_session_id": "0a76c25669713d8d6d306ba8c21259b7", } } ``` #### Complete Request with All Fields ```json { "transaction_info": { "type": "authorization", "reference_code": "1753550698549" }, "card": { "number": "4225289837059229", "expiration_date": "01/2030", "security_code": "123", "holder": "John Doe Jones" }, "order_info": { "amount_details": { "total_amount": 1000, "currency": "BRL", "items_amount": 1000, "shipping_amount": 20, "fee_amount": 10 }, "installments": 1, "descriptor": "Test Payment" }, "cardholder_info": { "first_name": "John", "last_name": "Doe", "document": { "type": "CPF", "number": "54672396002", "nationality": "BR" }, "gender": "MALE", "country": "BR", "address_1": "123 Main St", "address_2": "address 2", "city": "Sao Paulo", "state": "SP", "postal_code": "04001-000", "birth_date": "2025-07-01", "email": "john_autoaccept@test.com", "phone_number": "4158880000", "phone_type": "Mobile", "phone_country_code": "58", "phone_area_code": "22" }, "bill_to": { "id": "1234567890", "first_name": "John", "last_name": "Doe", "document": { "type": "CPF", "number": "54672396002", "nationality": "BR" }, "gender": "MALE", "country": "BR", "address_1": "123 Main St", "address_2": "address 2", "city": "Sao Paulo", "state": "SP", "postal_code": "04001-000", "birth_date": "2025-07-01", "email": "test@cybs.com", "phone_number": "4158880000", "phone_type": "Mobile", "phone_area_code": "22", "profile": "1" }, "line_items": [ { "category": { "id": "1", "name": "Category 1" }, "discount_amount": 10, "id": "1", "name": "Item 1", "price": 1500, "quantity": 1, "seller_id": "seller id", "service_date": "2025-07-01", "type": "Generic" } ], "shipping_info": { "country": "BR", "address_1": "123 Main St", "address_2": "address 2", "city": "Sao Paulo", "state": "SP", "postal_code": "04001-000", "by": "DHL", "date": "2021-01-01T00:00:00.000Z", "type": "EXPRESS", "price": 1000 }, "device_info": { "ip_address": "127.0.0.1", "fingerprint_session_id": "0a76c25669713d8d6d306ba8c21259b7", } } ``` ### Field Specifications All field specifications are identical to the [Payment endpoint](/api-docs/api-reference/payments/payments-api-koin/payments-complete-flow.md), except: * `transaction_info.type` must be `"authorization"` ### Response Format #### Success Response (200) ```json { "status_code": 200, "status": "Success", "desc": "Authorization processed successfully", "data": { "transaction_info": { "type": "authorization_response", "reference_code": "1753550698549", "transaction_id": "0001753550699162992390", "request_id": "10cf95b7-746f-4fba-bb02-d7f53f64fb6c", "status": "Authorized", "response_code": "4389437", "created_at": "2025-07-26T17:25:06.759Z" }, "order_info": { "amount_details": { "authorized_amount": 1000, "currency": "BRL" } }, "risk_info": { "status": "Approved", "date": "2025-07-26T17:25:06.000Z", "strategies": [] } } } ``` #### Failed Authorization Response (200) ```json { "status": "success", "message": "Authorization failed", "data": { "transaction_info": { "type": "authorization_response", "reference_code": "1753550023570", "transaction_id": "0001755131293054685902", "request_id": "6aaac7d1-3be3-4721-96a0-a8d5f5b607a9", "status": "Declined", "created_at": "2025-08-14T00:28:17.265Z" }, "order_info": { "amount_details": { "authorized_amount": 10001, "currency": "BRL" } }, "risk_info": { "status": "Approved", "date": "2025-08-14T00:28:16.000Z", "strategies": [] }, "error_info": { "reason": "InsufficientFunds", "message": "Transaction failed" } } } ``` #### Error Response (400/500) ```json { "status": "Fail", "message": "Invalid request", "data": { "code": 400, "description": "Invalid card data." } } ``` ### Response Fields #### transaction\_info | Field | Type | Description | | ---------------- | ------ | ---------------------------------------------------------------- | | `type` | String | Response type (authorization\_response, payment\_response, etc.) | | `reference_code` | String | Merchant reference code from request | | `transaction_id` | String | Unique transaction identifier generated by KOIN | | `request_id` | String | Unique request identifier | | `status` | String | Transaction status (Authorized, Declined, Opened) | | `response_code` | String | Internal response code | | `created_at` | String | Transaction creation timestamp (ISO 8601) | #### order\_info | Field | Type | Description | | ---------------------------------- | ------ | -------------------------- | | `amount_details.authorized_amount` | Number | Authorized amount in cents | | `amount_details.currency` | String | Transaction currency | #### risk\_info | Field | Type | Description | | ------------ | ------ | -------------------------------------------------------------- | | `status` | String | Antifraud status: `Approved`, `Denied` | | `date` | String | Date of antifraud evaluation (ISO 8601) | | `strategies` | Array | Array of antifraud strategies applied (see Strategies section) | #### error\_info (present when transaction fails) | Field | Type | Description | | --------- | ------ | ----------------------------------------------------- | | `reason` | String | Failure reason (InsufficientFunds, InvalidCard, etc.) | | `message` | String | Human-readable error message | #### Antifraud Strategies The `strategies` array contains objects with antifraud strategies that were applied to the transaction. Each strategy object contains: | Field | Type | Description | | ------ | ------ | ------------------------------------------------------------------------------------------------ | | `type` | String | Strategy type (`VerificationCode` ,`DocumentScan` ,`ManualVerification` ,`CollectAuthRecovery` ) | | `link` | String | Reference link for strategy details | **Note**: Strategies must be configured in your KOIN account to appear in responses. If no strategies are configured, the array will be empty `[]`. ### cURL Example ```bash curl -X POST https://api.firstoken.co/v1/payments/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "transaction_info": { "type": "authorization", "reference_code": "ref_{{$guid}}" }, "card": { "number": "4225289837059229", "expiration_date": "01/2030", "security_code": "123", "holder": "João Silva" }, "order_info": { "amount_details": { "total_amount": 1000, "currency": "BRL", "items_amount": 1000 }, "installments": 1, "descriptor": "Pre-autorização" }, "cardholder_info": { "first_name": "João", "last_name": "Silva", "document": { "type": "CPF", "number": "12345678901", "nationality": "BR" }, "country": "BR", "address_1": "Rua das Flores, 123", "city": "São Paulo", "state": "SP", "postal_code": "04001-000", "email": "joao@example.com", "phone_number": "11987654321", "phone_type": "Mobile", "phone_area_code": "11" }, "bill_to": { "id": "customer_123", "first_name": "João", "last_name": "Silva", "document": { "type": "CPF", "number": "12345678901", "nationality": "BR" }, "country": "BR", "address_1": "Rua das Flores, 123", "city": "São Paulo", "state": "SP", "postal_code": "04001-000", "email": "joao@example.com", "phone_number": "11987654321", "phone_type": "Mobile", "phone_area_code": "11", "profile": "regular" }, "line_items": [ { "category": { "id": "1", "name": "Category 1" }, "id": "item_001", "name": "Produto Teste", "price": 1000, "quantity": 1, "type": "Physical" } ], "device_info": { "ip_address": "192.168.1.100" } }' ``` ### Important Notes #### Authorization Expiration * **Typical Expiration**: Authorizations expire after 7 days if not captured * **Best Practice**: Capture within 24-48 hours for best success rates #### Next Steps After Authorization After a successful authorization, you have three options: 1. [**Capture**](/api-docs/api-reference/payments/payments-api-koin/capture.md): Collect the authorized amount (or less) 2. [**Authorization Void**](/api-docs/api-reference/payments/payments-api-koin/authorization-void.md): Cancel the authorization 3. **Wait for Expiration**: Authorization will automatically expire #### Authorization vs Payment | Aspect | Authorization | Payment | | ----------------------- | -------------------------- | --------------------------- | | **Funds Collection** | Holds funds only | Collects funds immediately | | **Customer Experience** | Pending charge | Completed charge | | **Next Step Required** | Yes (capture or reversal) | No | | **Use Case** | Variable amounts, pre-auth | Fixed amounts, direct sales | | **Expiration** | 7 days typically | N/A (already collected) | --- # Agent Instructions: 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: ``` GET https://firstoken.gitbook.io/api-docs/api-reference/payments/payments-api-koin/authorization.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.