# 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

<table><thead><tr><th>Endpoint</th><th>Method</th><th>Description</th></tr></thead><tbody><tr><td><code>/v1/payments/</code></td><td>POST</td><td><strong>Complete Payment Flow</strong> - Tokenization + Authorization + Capture</td></tr><tr><td><code>/v1/payments/</code></td><td>POST</td><td><strong>Authorization Only</strong> - Authorize payment without capture</td></tr><tr><td><code>/v1/payments/{transactionId}/capture</code></td><td>POST</td><td><strong>Capture</strong> - Capture a previously authorized payment</td></tr><tr><td><code>/v1/payments/{transactionId}/refund</code></td><td>POST</td><td><strong>Payment Refund</strong> - Refund a completed payment</td></tr><tr><td><code>/v1/payments/{transactionId}/void</code></td><td>POST</td><td><strong>Authorization Void</strong> - Void an authorization</td></tr><tr><td><pre><code>v1/payments/transactions/{transactionId}
</code></pre></td><td>GET</td><td><strong>Transaction Details</strong> - Get transaction last update</td></tr></tbody></table>

### 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                     |
| `Declined`       | `Rejected`             | The transaction was declined. The acquirer does not allow this transaction to be processed                          |
| `Declined`       | `InsufficientFunds`    | The transaction was declined because the card has insufficient funds. Please, try a different card                  |
| `Declined`       | `InvalidCard`          | The transaction was declined because the card details are invalid. Please, try again                                |
| `Declined`       | `Referred`             | The transaction was declined. The customer should contact their bank                                                |
| `Declined`       | `ExpiredCard`          | The transaction was declined because the card is expired. Please, try a different card                              |
| `ProcessorError` | `InvalidConfiguration` | The transaction was declined due to a processing error. Contact Firstoken for more details                          |
| `ProcessorError` | `Undefined`            | The transaction was declined due to an unexpected error                                                             |
| `Declined`       | `StolenCard`           | The transaction was declined because the card is reported as stolen, related to fraud. Please, try a different card |
| `ProcessorError` | `ConnectionRejected`   | The transaction was declined due to a processing error. The acquirer and supplier are working on it                 |
| `Declined`       | `InvalidData`          | The transaction was declined due to a processing error. Contact Firstoken for more details                          |
| `Declined`       | `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)**](/api-docs/api-reference/payments/payments-api-koin/payments-complete-flow.md) - One-call payment processing
* [**Authorization**](/api-docs/api-reference/payments/payments-api-koin/authorization.md) - Authorization-only transactions
* [**Capture**](/api-docs/api-reference/payments/payments-api-koin/capture.md) - Capture authorized payments
* [**Payment Refund**](/api-docs/api-reference/payments/payments-api-koin/payment-refund.md) - Void completed payments
* [**Authorization Void**](/api-docs/api-reference/payments/payments-api-koin/authorization.md) - Reverse authorizations
* [**Testing Guide** ](/api-docs/api-reference/payments/payments-api-koin/testing-guide.md)- Test cards, amounts, and scenarios


---

# 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.md?ask=<question>
```

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.