# Payments API - KOIN ### Overview This API provides a comprehensive interface for processing payments through KOIN. This API offers multiple endpoints for different payment operations, from simple authorizations to complete payment flows with automatic tokenization and capture. **Key Features:** * **Multiple Payment Flows**: Choose between authorization-only or complete payment processing * **Advanced Integration**: Full tokenization, authorization, and capture capabilities * **Flexible Operations**: Support for capture, void, and reversal operations * **Comprehensive Data**: Rich transaction data collection for optimal processing **Important**: To use these payment endpoints, you must contact Firstoken to enable payment processing capabilities in your account. ### Base URLs * **Production**: `https://api.firstoken.co/v1/payments/` * **Sandbox**: `https://api.firstoken-staging.co/v1/payments/` *(for testing only)* ### Authentication All API requests require authentication using an API key in the `x-api-key` header: ```bash curl -X POST https://api.firstoken.co/v1/payments/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{...}' ``` ### Available Endpoints
EndpointMethodDescription
/v1/payments/POSTComplete Payment Flow - Tokenization + Authorization + Capture
/v1/payments/POSTAuthorization Only - Authorize payment without capture
/v1/payments/{transactionId}/capturePOSTCapture - Capture a previously authorized payment
/v1/payments/{transactionId}/refundPOSTPayment Refund - Refund a completed payment
/v1/payments/{transactionId}/voidPOSTAuthorization Void - Void an authorization
v1/payments/transactions/{transactionId}
GETTransaction Details - Get transaction last update
### Transaction Types The API supports different transaction types specified in the `transaction_info.type` field: | Type | Description | Use Case | | -------------------- | ----------------------------------------------------- | ---------------------------------- | | `payment` | Complete payment flow (tokenization + auth + capture) | Direct sales, immediate collection | | `authorization` | Authorization only | Pre-authorization, capture later | | `capture` | Capture authorized amount | Complete pre-authorized payment | | `payment_refund` | Void completed payment | Cancel completed transaction | | `authorization_void` | Reverse authorization | Cancel authorization | ### Common Request Fields #### transaction\_info (Required for all requests) ```json { "type": "payment", // or "authorization", "capture", etc. "reference_code": "merchant_reference" } ``` #### card (Required for payment/authorization) ```json { "number": "4225289837059229", "expiration_date": "01/2030", "security_code": "123", "holder": "John Doe Jones" } ``` #### order\_info (Required for payment/authorization) ```json { "amount_details": { "total_amount": 1000, "currency": "BRL", "items_amount": 1000 }, "installments": 1, "descriptor": "Payment Description" } ``` #### cardholder\_info (Required for payment/authorization) ```json { "first_name": "John", "last_name": "Doe", "document": { "type": "CPF", "number": "54672396002", "nationality": "BR" }, "country": "BR", "address_1": "123 Main St", "city": "São Paulo", "state": "SP", "postal_code": "04001-000", "email": "customer@example.com", "phone_number": "4158880000", "phone_type": "Mobile", "phone_area_code": "22" } ``` ### Status Codes | HTTP Code | Description | | --------- | ------------------------------------- | | 200 | Success | | 400 | Bad Request - Invalid request | | 403 | Access Denied - Authentication failed | | 500 | Internal Server Error | ### Transaction Status Values | Status | Reason | Description | | ------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------- | | `Opened` | - | The order was created and in progress | | `Authorized` | - | The order was authorized | | `Collected` | - | The order was created and paid for | | `Cancelled` | - | The state of an *Opened* order that expired or was cancelled by calling cancellation operation | | `Voided` | - | The state of an *Authorized* order that expired or was voided by calling cancellation operation | | `Failed` | `Rejected` | The transaction was declined. The acquirer does not allow this transaction to be processed | | `Failed` | `InsufficientFunds` | The transaction was declined because the card has insufficient funds. Please, try a different card | | `Failed` | `InvalidCard` | The transaction was declined because the card details are invalid. Please, try again | | `Failed` | `Referred` | The transaction was declined. The customer should contact their bank | | `Failed` | `ExpiredCard` | The transaction was declined because the card is expired. Please, try a different card | | `Failed` | `InvalidConfiguration` | The transaction was declined due to a processing error. Contact Firstoken for more details | | `Failed` | `Undefined` | The transaction was declined due to an unexpected error | | `Failed` | `StolenCard` | The transaction was declined because the card is reported as stolen, related to fraud. Please, try a different card | | `Failed` | `ConnectionRejected` | The transaction was declined due to a processing error. The acquirer and supplier are working on it | | `Failed` | `InvalidData` | The transaction was declined due to a processing error. Contact Firstoken for more details | | `Failed` | `Antifraud` | The transaction was declined for antifraud | ### Getting Started 1. **Account Configuration**: Our team will configure your account 2. **API Keys**: Create your sandbox and production API keys 3. **Contact Firstoken**: to request payment processing activation 4. **Testing**: Test integration using the sandbox environment 5. **Go Live**: Deploy to production after successful testing *** ### Navigation * [**Payments (Complete Flow)**](https://firstoken.gitbook.io/api-docs/api-reference/firstoken-api/payments/payments-api-koin/payments-complete-flow) - One-call payment processing * [**Authorization**](https://firstoken.gitbook.io/api-docs/api-reference/firstoken-api/payments/payments-api-koin/authorization) - Authorization-only transactions * [**Capture**](https://firstoken.gitbook.io/api-docs/api-reference/firstoken-api/payments/payments-api-koin/capture) - Capture authorized payments * [**Payment Refund**](https://firstoken.gitbook.io/api-docs/api-reference/firstoken-api/payments/payments-api-koin/payment-refund) - Void completed payments * [**Authorization Void**](https://firstoken.gitbook.io/api-docs/api-reference/firstoken-api/payments/payments-api-koin/authorization) - Reverse authorizations * [**Testing Guide** ](https://firstoken.gitbook.io/api-docs/api-reference/firstoken-api/payments/payments-api-koin/testing-guide)- Test cards, amounts, and scenarios