# Payments - Complete Flow

### Overview

The Payments endpoint processes a complete payment transaction with automatic tokenization, authorization, and capture in a single API call. This is the most common endpoint for direct sales where you want immediate payment collection.

**POST** `/v1/payments/`

### What Happens Internally

```
Client Request → Firstoken API → [Tokenization + Authorization + Capture] → Response
```

1. **Tokenization**: Card data is securely tokenized
2. **Authorization**: Payment is authorized with the token
3. **Capture**: Payment is automatically captured
4. **Response**: Single response with the complete transaction result

### Request Body

#### Minimal Required Fields

```json
{
  "transaction_info": {
    "type": "payment",
    "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": {
    "fingerprint_session_id": "0a76c25669713d8d6d306ba8c21259b7",
    "ip_address": "127.0.0.1"
  }
}
```

#### Complete Request with All Fields

```json
{
  "transaction_info": {
    "type": "payment",
    "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"
  }
}
```

### Field Specifications

#### transaction\_info (Required)

| Field            | Type   | Required | Description             |
| ---------------- | ------ | -------- | ----------------------- |
| `type`           | String | Yes      | Must be "payment"       |
| `reference_code` | String | Yes      | Merchant reference code |

#### card (Required)

| Field             | Type   | Required | Description                           |
| ----------------- | ------ | -------- | ------------------------------------- |
| `number`          | String | Yes      | Card number                           |
| `expiration_date` | String | Yes      | Card expiration (MM/YYYY format)      |
| `security_code`   | String | Yes      | CVV/CVC code (3-4 digits)             |
| `holder`          | String | Yes      | Cardholder name as it appears on card |

#### order\_info (Required)

| Field                            | Type   | Required | Description                    |
| -------------------------------- | ------ | -------- | ------------------------------ |
| `amount_details.total_amount`    | Number | Yes      | Total transaction amount       |
| `amount_details.currency`        | String | Yes      | Currency code (BRL, USD, etc.) |
| `amount_details.items_amount`    | Number | Yes      | Sum of line items amount       |
| `amount_details.shipping_amount` | Number | No       | Shipping cost                  |
| `amount_details.fee_amount`      | Number | No       | Additional fees                |
| `installments`                   | Number | Yes      | Number of installments         |
| `descriptor`                     | String | Yes      | Payment descriptor             |

#### cardholder\_info (Required)

| Field                  | Type   | Required | Description                     |
| ---------------------- | ------ | -------- | ------------------------------- |
| `first_name`           | String | Yes      | First name                      |
| `last_name`            | String | Yes      | Last name                       |
| `document.type`        | String | Yes      | Document type (CPF, CNPJ)       |
| `document.number`      | String | Yes      | Document number                 |
| `document.nationality` | String | Yes      | Document nationality (BR)       |
| `country`              | String | Yes      | Country code                    |
| `address_1`            | String | Yes      | Primary address                 |
| `city`                 | String | Yes      | City name                       |
| `state`                | String | Yes      | State code                      |
| `postal_code`          | String | Yes      | Postal code                     |
| `email`                | String | Yes      | Email address                   |
| `phone_number`         | String | Yes      | Phone number                    |
| `phone_type`           | String | No       | Phone type (Mobile, Home, Work) |
| `phone_area_code`      | String | Yes      | Area code                       |
| `gender`               | String | No       | Gender (MALE, FEMALE, OTHER)    |
| `birth_date`           | String | No       | Birth date (YYYY-MM-DD)         |
| `address_2`            | String | No       | Secondary address               |
| `phone_country_code`   | String | No       | Phone country code              |

#### bill\_to (Required)

| Field            | Type    | Required                 | Description         |
| ---------------- | ------- | ------------------------ | ------------------- |
| `id`             | String  | No                       | Customer identifier |
| `profile`        | String  | No                       | Customer profile    |
| All other fields | Various | Same as cardholder\_info | Same requirements   |

#### line\_items (Required)

| Field             | Type   | Required | Description               |
| ----------------- | ------ | -------- | ------------------------- |
| `id`              | String | Yes      | Item identifier           |
| `name`            | String | Yes      | Item name                 |
| `price`           | Number | Yes      | Item price                |
| `quantity`        | Number | Yes      | Item quantity             |
| `type`            | String | No       | Item type must be Generic |
| `category.id`     | String | No       | Category identifier       |
| `category.name`   | String | No       | Category name             |
| `seller_id`       | String | No       | Seller identifier         |
| `service_date`    | String | No       | Service date              |
| `discount_amount` | Number | No       | Discount applied          |

#### device\_info (Recommended)

| Field        | Type   | Required | Description         |
| ------------ | ------ | -------- | ------------------- |
| `ip_address` | String | No       | Customer IP address |

#### shipping\_info (Optional)

| Field         | Type   | Required | Description                       |
| ------------- | ------ | -------- | --------------------------------- |
| `country`     | String | No       | Shipping country                  |
| `address_1`   | String | No       | Shipping address                  |
| `city`        | String | No       | Shipping city                     |
| `state`       | String | No       | Shipping state                    |
| `postal_code` | String | No       | Shipping postal code              |
| `by`          | String | No       | Shipping carrier                  |
| `date`        | String | No       | Expected delivery date            |
| `type`        | String | No       | Shipping type (STANDARD, EXPRESS) |
| `price`       | Number | No       | Shipping cost                     |

### Response Format

#### Success Response (200)

```json
{
  "status_code": 200,
  "status": "Success",
  "desc": "Payment processed successfully",
  "data": {
    "transaction_info": {
      "type": "payment_response",
      "reference_code": "1753550831362",
      "transaction_id": "0001753550831987788592",
      "request_id": "6a67ceba-9c66-4c80-b567-6f821cff007b",
      "status": "Collected",
      "response_code": "6344942",
      "created_at": "2025-07-26T17:27:17.931Z"
    },
    "order_info": {
      "amount_details": {
        "authorized_amount": 1000,
        "currency": "BRL"
      }
    },
    "risk_info": {
      "status": "Approved",
      "date": "2025-07-26T17:27:16.000Z",
      "strategies": []
    }
  }
}
```

#### Failed Payment Response (200)

```json
{
  "status": "success",
  "message": "Payment failed",
  "data": {
    "transaction_info": {
      "type": "payment_response",
      "reference_code": "1753550023570",
      "transaction_id": "0001755176590033234494",
      "request_id": "6de98d6d-1a49-438e-a648-23644c5856f1",
      "status": "Declined",
      "created_at": "2025-08-14T13:03:15.419Z"
    },
    "order_info": {
      "amount_details": {
        "authorized_amount": 10001,
        "currency": "BRL"
      }
    },
    "risk_info": {
      "status": "Approved",
      "date": "2025-08-14T13:03:14.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 (payment\_response, authorization\_response, etc.) |
| `reference_code` | String | Merchant reference code from request                             |
| `transaction_id` | String | Unique transaction identifier generated by Firstoken             |
| `request_id`     | String | Unique request identifier                                        |
| `status`         | String | Transaction status (Collected, Declined, Pending, etc.)          |
| `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    |
| `amount_details.currency`          | String | Transaction currency |

#### risk\_info

| Field        | Type   | Description                                                    |
| ------------ | ------ | -------------------------------------------------------------- |
| `status`     | String | Antifraud status: `Approved`, `Rejected`, `Pending`            |
| `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": "payment",
      "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": "Compra Online"
    },
    "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": "Generic"
      }
    ],
    "device_info": {
      "ip_address": "192.168.1.100"
    }
  }'
```
