Selva API

https://docs.selva.fi.cr
Admin
Selva API is a financial services platform that enables businesses to integrate payment processing,...
Tokens:24,289
Snippets:151
Trust Score:2.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### Idempotency Key Header Example

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Example value for the required X-Idempotency-Key header.

```yaml
example: 'UUID'
```

--------------------------------

### Payment Request Examples

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Examples of valid request bodies for different types of payment transfers.

```yaml
PIN Transfer:
  value:
    from_account_id: 70242935-a11b-4018-8e84-0413a8ac9d67
    amount: 1000
    recipient_iban: CR02010200000000000001
```

```yaml
SINPE MÃ³vil Transfer:
  value:
    from_account_id: 70242935-a11b-4018-8e84-0413a8ac9d67
    amount: 2500
    recipient_phone: '88881234'
```

--------------------------------

### Payment History Example

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

This example demonstrates the structure of a successful response when retrieving payment history. It includes details for multiple payments, such as IDs, status, amounts, and payer/payee information.

```json
{
  "success": true,
  "message": "Payment history retrieved successfully",
  "data": {
    "payments": [
      {
        "id": "09382be6-3df3-4fb1-9800-a2d07e765e70",
        "idempotency_key": "5e54af47-ddaf-41cd-ac05-ae39a5b26809",
        "cgp_ref_number": 10260,
        "channel_ref_number": "2026010500001490851047982",
        "sinpe_ref": "2026010537022010000102609",
        "transfer_type": "debit",
        "status": "completed",
        "amount": {
          "value": 100,
          "currency": "CRC",
          "formatted": "1.00 CRC"
        },
        "description": null,
        "reference": null,
        "error_message": null,
        "created_at": "2026-01-05T16:54:36.000000Z",
        "submitted_at": "2026-01-05T16:54:44.000000Z",
        "completed_at": "2026-01-05T16:54:44.000000Z",
        "payment_type": "pin",
        "payer": {
          "iban": "CR06037010600471851492",
          "document_number": "0700000021",
          "name": "Bob Darl"
        },
        "payee": {
          "document_number": "0101110114",
          "name": "CARLOS ALBERTO AMADOR HIDALGO",
          "iban": "CR02010200000000000001"
        }
      },
      {
        "id": "ca43e1b9-ae79-4e52-8712-791d474a1ede",
        "idempotency_key": "a3f21177-d5df-4fc2-bddb-063cd0283316",
        "cgp_ref_number": 10259,
        "channel_ref_number": "2026010500001270607738051",
        "sinpe_ref": "2026010537022010000102590",
        "transfer_type": "debit",
        "status": "completed",
        "amount": {
          "value": 1700,
          "currency": "CRC",
          "formatted": "17.00 CRC"
        },
        "description": null
      }
    ]
  }
}
```

--------------------------------

### Retrieve Paginated Payment History

Source: https://docs.selva.fi.cr/docs/api-reference

Example of a GET request to the payment history endpoint using limit and offset parameters.

```http
GET /api/payments/history?limit=20&offset=0  
```

--------------------------------

### Validation Error Response Examples

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Examples of error responses returned when payment validation fails due to business logic or missing headers.

```yaml
Single Validation Error:
  value:
    success: false
    message: Amount exceeds maximum limit
    data: null
    errors:
      amount:
        - Amount exceeds maximum limit
```

```yaml
Multiple Validation Errors:
  value:
    success: false
    message: Source account does not exist
    data: null
    errors:
      from_account_id:
        - Source account does not exist
        - You do not own this account
      amount:
        - Amount exceeds maximum limit
```

```yaml
Both Recipient Fields Provided:
  value:
    success: false
    message: Only one recipient field should be provided
    data: null
    errors:
      recipient:
        - Cannot provide both recipient_iban and recipient_phone
```

```yaml
Missing Idempotency Key:
  value:
    success: false
    message: X-Idempotency-Key header is required
    data: null
    errors:
      X-Idempotency-Key:
        - X-Idempotency-Key header is required
```

--------------------------------

### GET /api/iban/information/{iban}

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Retrieves information about a given IBAN, verifying if it is registered in the system.

```APIDOC
## GET /api/iban/information/{iban}

### Description
Retrieves information about a given IBAN, verifying if it is registered in the system.

### Method
GET

### Endpoint
/api/iban/information/{iban}

### Parameters
#### Path Parameters
- **iban** (string) - Required - The IBAN to verify. Must follow the pattern '^CR\d{20}$'.

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the result of the operation.
- **data** (object) - Contains the IBAN details if successful.
  - **iban** (string) - The IBAN.
  - **name** (string) - The name associated with the IBAN.
  - **document_number** (string) - Raw document number (no dashes).
  - **currency** (string) - The currency associated with the IBAN.
  - **country_code** (string) - The country code.
  - **entity_name** (string) - The name of the entity associated with the IBAN.
  - **status** (string) - The status of the IBAN verification.

#### Response Example
```json
{
  "example": "{\n  \"success\": true,\n  \"message\": \"IBAN information retrieved successfully\",\n  \"data\": {\n    \"iban\": \"CR02010200000000000001\",\n    \"name\": \"Juan Perez\",\n    \"document_number\": \"0100000001\",\n    \"currency\": \"CRC\",\n    \"country_code\": \"CR\",\n    \"entity_name\": \"Banco BAC San JosÃ©\",\n    \"status\": \"registered\"\n  }\n}"
}
```
```

--------------------------------

### GET /api/phone/information/{phone}

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Verifies if a given phone number is registered in the system.

```APIDOC
## GET /api/phone/information/{phone}

### Description
Verifies if a given phone number is registered in the system.

### Method
GET

### Endpoint
/api/phone/information/{phone}

### Parameters
#### Path Parameters
- **phone** (string) - Required - The phone number to verify. Must follow the pattern '^(506)?[678]\d{7}$'.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.

#### Response Example
(Response body structure for success is not fully defined in the provided text, but it would typically include information about the phone number's registration status.)

#### Error Response (Example - specific error codes and structures not fully detailed in the provided text)
(Error responses would typically follow a similar structure to other endpoints, indicating failure with appropriate messages and error details.)
```

--------------------------------

### Costa Rican IBAN Example

Source: https://docs.selva.fi.cr/api-reference

Example of a valid Costa Rican IBAN number format.

```text
CR02010200000000000001
```

--------------------------------

### Retry Logic Implementation

Source: https://docs.selva.fi.cr/docs/errors

Example of implementing retry logic for transient errors (5xx status codes) using JavaScript.

```APIDOC
## Error Handling Strategies

### 1. Retry Logic

Implement retry logic for transient errors (5xx status codes):

```javascript
async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.ok) {
        return await response.json();
      }

      // Don't retry client errors
      if (response.status >= 400 && response.status < 500) {
        const error = await response.json();
        throw new Error(error.message);
      }

      // Retry server errors
      if (response.status >= 500) {
        throw new Error('Server error');
      }
    } catch (error) {
      if (attempt === maxRetries - 1) {
        throw error;
      }

      // Exponential backoff
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}
```
```

--------------------------------

### Costa Rican National ID Example

Source: https://docs.selva.fi.cr/api-reference

Example of a valid Costa Rican national ID (Cédula) format.

```text
0123456789
```

--------------------------------

### GET /api/user

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Retrieves the authenticated user's profile information.

```APIDOC
## GET /api/user

### Description
Retrieves the details of the currently authenticated user.

### Method
GET

### Endpoint
/api/user

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **message** (string) - Status message
- **data** (object) - User profile details including id, name, email, and timestamps

#### Response Example
{
  "success": true,
  "message": "User retrieved successfully",
  "data": {
    "id": "d37da6d4-c34c-44e9-bb00-7273a378a5ad",
    "name": "Bob Dalf",
    "email": "bob@selva.com",
    "email_verified_at": null,
    "created_at": "2025-12-12T13:30:05.000000Z",
    "updated_at": "2025-12-12T13:31:58.000000Z"
  }
}
```

--------------------------------

### Get User Request (cURL)

Source: https://docs.selva.fi.cr/api-reference

Use this cURL command to retrieve user information. Ensure you replace 'YOUR_SECRET_TOKEN' with your actual bearer token for authentication.

```shell
curl --request GET \
  --url https://dev.selva.fi.cr/api/user \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

--------------------------------

### GET /api/webhooks/subscriptions

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Retrieves a list of webhook subscriptions.

```APIDOC
## GET /api/webhooks/subscriptions

### Description
Retrieves a list of webhook subscriptions. Supports pagination via query parameters.

### Method
GET

### Endpoint
/api/webhooks/subscriptions

### Parameters
#### Query Parameters
- **per_page** (integer) - Optional - The number of items to return per page. Minimum: 1, Maximum: 1000. Example: 15

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the result of the request.
- **data** (object) - Contains the webhook subscription data.
  - **current_page** (integer) - The current page number.
  - **data** (array) - An array of webhook subscription objects.
    - **id** (string) - The unique identifier for the webhook subscription (UUID format).
    - **user_id** (string) - The ID of the user associated with the subscription (UUID format).
    - **url** (string) - The URL to which webhook events will be sent. Max length: 2048.
    - **events** (array) - A list of events that will trigger this webhook.
      - (string) - Enum: payment.created, payment.processing, payment.completed, payment.failed, transaction.received.
    - **active** (boolean) - Indicates if the webhook subscription is active.
    - **max_attempts** (integer) - The maximum number of retry attempts for sending events.
    - **timeout** (integer) - The timeout in seconds for sending events.
    - **headers** (object) - Custom headers to include in the webhook request.
      - (string) - Additional properties are allowed, values are strings.
    - **last_sent_at** (string) - The timestamp of the last successful event delivery (ISO 8601 format), nullable.
    - **created_at** (string) - The timestamp when the subscription was created (ISO 8601 format).
    - **updated_at** (string) - The timestamp when the subscription was last updated (ISO 8601 format).
    - **suspended_at** (string) - The timestamp when the subscription was suspended (ISO 8601 format), nullable.
    - **suspended_reason** (string) - The reason for suspension, nullable.
  - **first_page_url** (string) - The URL for the first page of results, nullable.
  - **from** (integer) - The starting item number for the current page, nullable.
  - **last_page** (integer) - The last page number.
  - **last_page_url** (string) - The URL for the last page of results.
  - **links** (array) - Pagination links.
    - **url** (string) - The URL for the pagination link, nullable.
    - **label** (string) - The label for the pagination link.
    - **page** (integer) - The page number, nullable.
    - **active** (boolean) - Indicates if this pagination link is active.

#### Response Example
{
  "success": true,
  "message": "Webhook subscriptions retrieved successfully",
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "user_id": "f0e9d8c7-b6a5-4321-0fed-cba987654321",
        "url": "https://example.com/webhook",
        "events": [
          "payment.created",
          "payment.completed"
        ],
        "active": true,
        "max_attempts": 5,
        "timeout": 30,
        "headers": {
          "X-Custom-Header": "Value"
        },
        "last_sent_at": null,
        "created_at": "2023-10-27T10:00:00Z",
        "updated_at": "2023-10-27T10:00:00Z",
        "suspended_at": null,
        "suspended_reason": null
      }
    ],
    "first_page_url": "?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "?page=1",
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "page": null,
        "active": false
      },
      {
        "url": "?page=1",
        "label": "1",
        "page": 1,
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo",
        "page": null,
        "active": false
      }
    ]
  }
}

#### Error Response (422)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the error.
- **data** (object) - Nullable.
- **errors** (object) - Contains validation errors.
  - **field_name** (array) - An array of error messages for the specific field.

#### Response Example
{
  "success": false,
  "message": "Validation failed",
  "data": null,
  "errors": {
    "id": [
      "The id field must be a valid UUID."
    ]
  }
}
```

--------------------------------

### GET /api/phone/information/{phone_number}

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Retrieves information about a given phone number from the SINPE registry.

```APIDOC
## GET /api/phone/information/{phone_number}

### Description
Retrieves information about a given phone number from the SINPE registry.

### Method
GET

### Endpoint
/api/phone/information/{phone_number}

### Parameters
#### Path Parameters
- **phone_number** (string) - Required - The phone number to verify.

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the result of the operation.
- **data** (object) - Contains the phone number details if successful.
  - **phone_number** (string) - The phone number.
  - **name** (string) - The name associated with the phone number.
  - **document_number** (string) - Raw document number (no dashes).
  - **currency** (string) - The currency associated with the account.
  - **country_code** (string) - The country code.
  - **entity_name** (string) - The name of the entity associated with the phone number.
  - **status** (string) - The status of the phone verification.

#### Response Example
```json
{
  "example": "{\n  \"success\": true,\n  \"message\": \"Phone information retrieved successfully\",\n  \"data\": {\n    \"phone_number\": \"77770001\",\n    \"name\": \"Juan Perez\",\n    \"document_number\": \"0100000001\",\n    \"currency\": \"CRC\",\n    \"country_code\": \"CR\",\n    \"entity_name\": \"Banco BAC San JosÃ©\",\n    \"status\": \"registered\"\n  }\n}"
}
```

#### Error Response (404)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the error.
- **data** (object) - Null, as there is no data in case of an error.
- **errors** (object) - An empty object.

#### Error Response Example (404)
```json
{
  "example": "{\n  \"success\": false,\n  \"message\": \"Phone number not found in SINPE registry\",\n  \"data\": null,\n  \"errors\": {}\n}"
}
```

#### Error Response (422)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the validation error.
- **data** (object) - Null, as there is no data in case of an error.
- **errors** (object) - Contains validation errors for specific fields.
  - **phone** (array) - An array of strings describing the phone validation errors.

#### Error Response Example (422)
```json
{
  "example": "{\n  \"success\": false,\n  \"message\": \"Phone number must be a valid Costa Rican phone number (8 digits starting with 6, 7, or 8)\",\n  \"data\": null,\n  \"errors\": {\n    \"phone\": [\n      \"Phone number must be a valid Costa Rican phone number (8 digits starting with 6, 7, or 8)\"\n    ]\n  }\n}"
}
```

#### Error Response (500)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the internal server error.
- **data** (object) - Null, as there is no data in case of an error.
- **errors** (object) - An empty object.

#### Error Response Example (500)
```json
{
  "example": "{\n  \"success\": false,\n  \"message\": \"Unable to retrieve phone information\",\n  \"data\": null,\n  \"errors\": {}\n}"
}
```
```

--------------------------------

### Costa Rican Phone Number Example

Source: https://docs.selva.fi.cr/api-reference

Example of a valid Costa Rican phone number format, optionally prefixed with the country code.

```text
88881234
```

--------------------------------

### GET /api/user

Source: https://docs.selva.fi.cr/api-reference

Retrieves user information. Requires Bearer token authentication.

```APIDOC
## GET /api/user

### Description
Retrieves the user's information.

### Method
GET

### Endpoint
/api/user

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer Token for authentication.

### Request Example
```curl
curl --request GET \
  --url https://dev.selva.fi.cr/api/user \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the result of the operation.
- **data** (object) - Contains the user's details.
  - **id** (string) - The unique identifier of the user.
  - **name** (string) - The name of the user.
  - **email** (string) - The email address of the user.
  - **email_verified_at** (string) - The timestamp when the email was verified, or null.
  - **created_at** (string) - The timestamp when the user was created.
  - **updated_at** (string) - The timestamp when the user was last updated.

#### Error Response (401)
- **message** (string) - Indicates that the request is unauthenticated.
```

--------------------------------

### GET /api/webhooks/subscriptions

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Retrieves a paginated list of all webhook subscriptions for the authenticated user.

```APIDOC
## GET /api/webhooks/subscriptions

### Description
Retrieves a paginated list of webhook subscriptions.

### Method
GET

### Endpoint
/api/webhooks/subscriptions

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **message** (string) - Status message
- **data** (object) - Paginated list of webhook subscriptions

#### Response Example
{
  "success": true,
  "message": "Webhook subscriptions retrieved successfully",
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": "071c00a7-e248-437a-b42a-171eb087c704",
        "user_id": "d37da6d4-c34c-44e9-bb00-7273a378a5ad",
        "url": "https://api04.bullbitcoin.dev/selva/payment",
        "events": ["payment.created", "payment.processing", "payment.completed", "payment.failed", "transaction.received"],
        "active": false,
        "max_attempts": 5,
        "timeout": 30,
        "headers": {"X-Custom-Header": "value"},
        "last_sent_at": null,
        "created_at": "2025-12-15T21:27:25.000000Z",
        "updated_at": "2025-12-15T22:41:23.000000Z",
        "suspended_at": "2025-12-15T22:41:23.000000Z",
        "suspended_reason": "Manual suspension"
      }
    ],
    "total": 2
  }
}
```

--------------------------------

### Example Error Response

Source: https://docs.selva.fi.cr/docs/authentication

This JSON object represents an error response when authentication fails, indicating an invalid or expired authorization code. Ensure your authorization codes are valid and used within their expiration period.

```json
{
  "error": "invalid_grant",
  "message": "The authorization code is invalid or has expired"
}
```

--------------------------------

### Example Validation Error Response

Source: https://docs.selva.fi.cr/docs/errors

This JSON structure represents detailed validation errors returned by payment and account creation endpoints. Use the 'details' field to inform users about specific input issues.

```json
{
  "error": "validation_error",
  "message": "Request validation failed",
  "details": {
    "amount": "Amount must be greater than 0",
    "currency": "Invalid currency code",
    "recipient_identifier": "Invalid account identifier format"
  }
}
```

--------------------------------

### GET /api/payments/service-status

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Retrieves the current status of the payment services (PIN and SINPE).

```APIDOC
## GET /api/payments/service-status

### Description
Retrieves the current status of the payment services (PIN and SINPE), including their availability and operational status.

### Method
GET

### Endpoint
/api/payments/service-status

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the result of the request.
- **data** (object) - Contains the service status information.
  - **pin_service** (object) - Status of the PIN service.
    - **available** (boolean) - Indicates if the PIN service is available.
    - **status** (string) - Operational status of the PIN service ('online' or 'offline').
  - **sinpe_service** (object) - Status of the SINPE service.
    - **available** (boolean) - Indicates if the SINPE service is available.
    - **status** (string) - Operational status of the SINPE service ('online' or 'offline').
  - **overall_status** (string) - The overall status of all payment services ('online', 'partial', or 'offline').

#### Response Example (200)
{
  "success": true,
  "message": "Service status retrieved successfully",
  "data": {
    "pin_service": {
      "available": true,
      "status": "online"
    },
    "sinpe_service": {
      "available": true,
      "status": "online"
    },
    "overall_status": "online"
  }
}
```

--------------------------------

### GET /api/accounts/{id}

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Retrieves the details of a specific account by its unique identifier.

```APIDOC
## GET /api/accounts/{id}

### Description
Retrieves the details of a specific account by its unique identifier.

### Method
GET

### Endpoint
/api/accounts/{id}

### Parameters
#### Path Parameters
- **id** (string, uuid) - Required - The unique identifier of the account.

### Response
#### Success Response (200)
- **success** (boolean) - Status of the request
- **message** (string) - Success message
- **data** (object) - Account details including id, iban, currency, created_at, and updated_at

#### Response Example
{
  "success": true,
  "message": "Account retrieved successfully",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "iban": "CR37012345678901234567",
    "currency": "CRC",
    "created_at": "2025-06-09T18:30:00.000000Z",
    "updated_at": "2025-06-09T18:30:00.000000Z"
  }
}
```

--------------------------------

### GET /api/accounts/{id}/details

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Retrieves detailed information for a specific account, identified by its unique ID.

```APIDOC
## GET /api/accounts/{id}/details

### Description
Retrieves detailed information for a specific account.

### Method
GET

### Endpoint
/api/accounts/{id}/details

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the account (UUID format).

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the outcome of the request.
- **data** (object) - Contains the account details.
  - **id** (string) - The account ID (UUID format).
  - **document_number** (string) - The account's document number.
  - **iban** (string) - The International Bank Account Number.
  - **origin_code** (string) - The origin code of the account.
  - **currency** (string) - The currency of the account (e.g., CRC, USD).
  - **owner_name** (string) - The name of the account owner.
  - **status** (string) - The status of the account.
  - **created_at** (string) - The timestamp when the account was created (ISO 8601 format).
  - **updated_at** (string) - The timestamp when the account was last updated (ISO 8601 format).

#### Response Example
{
  "success": true,
  "message": "Account details retrieved successfully",
  "data": {
    "id": "db88a007-f3c6-412c-9898-a800c8edfadf",
    "document_number": "0700000021",
    "iban": "CR06037010600471851492",
    "origin_code": "special_savings",
    "currency": "CRC",
    "owner_name": "Bob Darl",
    "status": "active",
    "created_at": "2026-01-03T08:01:44.000000Z",
    "updated_at": "2026-01-03T08:01:44.000000Z"
  }
}

#### Error Response (404)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the error.
- **data** (object) - Null, as there is no data in case of an error.
- **errors** (object) - An empty object in case of a 404 error.

#### Error Response Example (404)
{
  "success": false,
  "message": "Account not found",
  "data": null,
  "errors": {}
}

#### Error Response (422)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the validation error.
- **data** (object) - Null, as there is no data in case of an error.
- **errors** (object) - Contains validation errors, where keys are field names and values are arrays of error messages.

#### Error Response Example (422)
{
  "success": false,
  "message": "Account ID must be a valid UUID",
  "data": null,
  "errors": {
    "id": [
      "Account ID must be a valid UUID"
    ]
  }
}
```

--------------------------------

### Step 4: Use the Access Token

Source: https://docs.selva.fi.cr/docs/authentication

Include the obtained access token in the `Authorization` header for all subsequent API requests.

```APIDOC
### Request Example
```bash
curl -X GET https://dev.selva.fi.cr/api/accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Note
Include `Accept: application/json` on token and API calls to ensure consistent responses.
```

--------------------------------

### Step 2: Handle the Authorization Callback

Source: https://docs.selva.fi.cr/docs/authentication

After user authorization, the user is redirected back to your specified `redirect_uri` with an authorization code in the query parameters.

```APIDOC
### Endpoint
https://your-app.com/callback?code=AUTHORIZATION_CODE&state=optional_state

### Description
Extract the `code` parameter from the URL query string to use in the next step.
```

--------------------------------

### KYC & Onboarding API

Source: https://docs.selva.fi.cr/docs/overview

Endpoints for managing Know Your Customer (KYC) status, applications, and document submissions.

```APIDOC
## GET /api/kyc/status

### Description
Tracks the KYC status for a user.

### Method
GET

### Endpoint
/api/kyc/status

### Response
#### Success Response (200)
- **kyc_status** (string) - The current KYC status (e.g., 'pending', 'approved', 'rejected').

## GET/POST /api/kyc/application

### Description
Retrieves or creates a KYC application.

### Method
GET, POST

### Endpoint
/api/kyc/application

### Request Body (for POST)
- **application_details** (object) - Required - Details for creating a new KYC application.

### Response
#### Success Response (200)
- **application_id** (string) - The unique identifier for the KYC application.
- **status** (string) - The current status of the application.

## POST /api/kyc/submit

### Description
Submits a KYC application for review.

### Method
POST

### Endpoint
/api/kyc/submit

### Request Body
- **application_id** (string) - Required - The ID of the application to submit.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

## POST /api/kyc/document

### Description
Uploads documents for a KYC application.

### Method
POST

### Endpoint
/api/kyc/document

### Request Body
- **application_id** (string) - Required - The ID of the application.
- **document** (file) - Required - The document file to upload.
```

--------------------------------

### Step 1: Redirect User to Authorization Endpoint

Source: https://docs.selva.fi.cr/docs/authentication

Initiate the OAuth 2.0 flow by redirecting the user to the Selva API's authorization endpoint with the necessary parameters.

```APIDOC
## GET /oauth/authorize

### Description
Redirect the user to this endpoint to initiate the OAuth 2.0 authorization code flow.

### Method
GET

### Endpoint
https://dev.selva.fi.cr/oauth/authorize

### Parameters
#### Query Parameters
- **client_id** (string) - Required - Your application's client ID.
- **redirect_uri** (string) - Required - The URI to redirect to after authorization. Must match a registered redirect URI.
- **response_type** (string) - Required - Must be `code` for authorization code flow.
- **scope** (string) - Optional - Space-separated scopes you need (e.g., `read-user read-accounts send-payments manage-webhooks`).

### Request Example
```javascript
const authUrl = new URL('https://dev.selva.fi.cr/oauth/authorize');
authUrl.searchParams.set('client_id', 'your-client-id');
authUrl.searchParams.set('redirect_uri', 'https://your-app.com/callback');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'read-accounts send-payments');

// Redirect user to authUrl.toString()
window.location.href = authUrl.toString();
```
```

--------------------------------

### Create a Payment

Source: https://docs.selva.fi.cr/docs/getting-started

Submit a payment request using an idempotency key to prevent duplicate transactions.

```javascript
// 1. Get access token (from Step 2)  
const accessToken = 'your-access-token';  
  
// 2. Generate idempotency key (must be a UUID)  
const idempotencyKey = crypto.randomUUID();  
  
// 3. Create payment  
const paymentResponse = await fetch('https://dev.selva.fi.cr/api/payments', {  
  method: 'POST',  
  headers: {  
    Authorization: `Bearer ${accessToken}`,  
    'Content-Type': 'application/json',  
    'X-Idempotency-Key': idempotencyKey,  
  },  
  body: JSON.stringify({  
    from_account_id: '550e8400-e29b-41d4-a716-446655440000',  
    amount: 10000,  
    currency: 'CRC',  
    recipient_phone: '50671234567', // or use recipient_iban instead  
    description: 'Payment for services',  
    reference: 'REF-12345',  
  }),  
});  
  
const payment = await paymentResponse.json();  
console.log('Payment created:', payment);
```

--------------------------------

### GET /api/accounts

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Retrieves all accounts belonging to the authenticated user.

```APIDOC
## GET /api/accounts

### Description
Retrieve all accounts belonging to the authenticated user. Note: Response format will change soon.

### Method
GET

### Endpoint
/api/accounts

### Response
#### Success Response (200)
- **success** (boolean) - Status of the request
- **message** (string) - Success message
- **data** (array) - List of account objects

#### Response Example
{
  "success": true,
  "message": "Accounts retrieved successfully",
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "iban": "CR37012345678901234567",
      "currency": "CRC",
      "created_at": "2025-06-09T18:30:00.000000Z",
      "updated_at": "2025-06-09T18:30:00.000000Z"
    }
  ]
}
```

--------------------------------

### Selva API Error: not_found

Source: https://docs.selva.fi.cr/docs/errors

The requested resource could not be found. Verify that the resource ID is correct.

```json
{
  "error": "not_found",
  "message": "The requested resource was not found"
}

```

--------------------------------

### POST /api/accounts

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Creates a new account for the authenticated user. Requires specifying the currency type.

```APIDOC
## POST /api/accounts

### Description
Creates a new account for the authenticated user.

### Method
POST

### Endpoint
/api/accounts

### Parameters
#### Request Body
- **currency** (string) - Required - Currency for the account (CRC or USD)

### Request Example
{
  "currency": "CRC"
}

### Response
#### Success Response (201)
- **success** (boolean) - Status of the request
- **message** (string) - Success message
- **data** (object) - Account details including id, iban, currency, created_at, and updated_at

#### Response Example
{
  "success": true,
  "message": "Account created successfully",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "iban": "CR37012345678901234567",
    "currency": "CRC",
    "created_at": "2025-06-09T18:30:00.000000Z",
    "updated_at": "2025-06-09T18:30:00.000000Z"
  }
}
```

--------------------------------

### Get Payment Details

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Retrieves the details of a specific payment using its ID.

```APIDOC
## GET /api/payments/{id}

### Description
Retrieves the details of a specific payment.

### Method
GET

### Endpoint
/api/payments/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the payment (UUID format).

### Response
#### Success Response (200)
- **value** (integer) - The amount of the payment.
- **currency** (string) - The currency of the payment (e.g., 'CRC').
- **formatted** (string) - The formatted payment amount with currency.
- **description** (string) - Description of the payment (nullable).
- **reference** (string) - Reference for the payment (nullable).
- **error_message** (string) - Error message if any (nullable).
- **created_at** (string) - Timestamp when the payment was created.
- **submitted_at** (string) - Timestamp when the payment was submitted.
- **completed_at** (string) - Timestamp when the payment was completed.
- **payment_type** (string) - The type of payment (e.g., 'sinpe').
- **payer** (object) - Information about the payer.
  - **iban** (string) - Payer's IBAN.
  - **document_number** (string) - Payer's document number.
  - **name** (string) - Payer's name.
- **payee** (object) - Information about the payee.
  - **document_number** (string) - Payee's document number.
  - **name** (string) - Payee's name.
  - **phone_number** (string) - Payee's phone number.

#### Error Response (422)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the error.
- **data** (object) - Nullable data field.
- **errors** (object) - Object containing validation errors.
  - **payment_id** (array) - Array of strings describing the payment ID error.

#### Error Response (404)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the error.
- **data** (object) - Nullable data field.
- **errors** (object) - Empty object for not found errors.

### Response Example
```json
{
  "value": 1012,
  "currency": "CRC",
  "formatted": "10.12 CRC",
  "description": null,
  "reference": null,
  "error_message": null,
  "created_at": "2026-01-06T02:23:23.000000Z",
  "submitted_at": "2026-01-06T02:23:31.000000Z",
  "completed_at": "2026-01-06T02:23:31.000000Z",
  "payment_type": "sinpe",
  "payer": {
    "iban": "CR06037010600471851492",
    "document_number": "0700000021",
    "name": "Bob Darl"
  },
  "payee": {
    "document_number": "0100000001",
    "name": "Juan Perez",
    "phone_number": "77770001"
  }
}
```
```

--------------------------------

### GET /api/payments/{id}

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Retrieves the details and status of a specific payment by its ID.

```APIDOC
## GET /api/payments/{id}

### Description
Retrieves the status and details of a payment using its unique identifier.

### Method
GET

### Endpoint
/api/payments/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the payment

### Response
#### Success Response (200)
- **success** (boolean) - Status of the request
- **message** (string) - Success message
- **data** (object) - Payment object containing the ID
```

--------------------------------

### Get Historical Transfers

Source: https://docs.selva.fi.cr/assets/files/openapi-87539803513dcdd9d20fc7bd26979c53.yaml

Retrieves a history of past transfers with filtering options.

```APIDOC
## GET /api/payments/history

### Description
Retrieves a history of past transfers, allowing filtering by payment method, transfer type, recipient, and pagination.

### Method
GET

### Endpoint
/api/payments/history

### Parameters
#### Query Parameters
- **payment_method** (string) - Optional - Filters transfers by payment method. Allowed values: 'pin', 'sinpe'. Example: 'pin'.
- **transfer_type** (string) - Optional - Filters transfers by type. Allowed values: 'debit', 'credit'. Example: 'debit'.
- **recipient_identifier** (string) - Optional - Filters transfers by recipient's national identifier. Example: '111090807'.
- **limit** (integer) - Optional - The maximum number of results to return. Minimum: 1, Maximum: 1000. Example: 10.
- **offset** (integer) - Optional - The number of results to skip. Minimum: 0. Example: 0.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the result.
- **data** (object) - Contains the payment history.
  - **payments** (array) - An array of payment objects.
    - **id** (string) - Unique identifier for the payment (UUID format).
    - **idempotency_key** (string) - Idempotency key for the payment (UUID format).
    - **transfer_type** (string) - Type of transfer.
    - **channel_ref_number** (string) - Channel reference number.
    - **cgp_ref_number** (integer) - CGP reference number.
    - **sinpe_ref** (string) - SINPE reference number.
    - **status** (string) - Status of the payment.
    - **amount** (object) - Details about the payment amount.

### Response Example
```json
{
  "success": true,
  "message": "Payment history retrieved successfully",
  "data": {
    "payments": [
      {
        "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "idempotency_key": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",
        "transfer_type": "debit",
        "channel_ref_number": "CHN123456",
        "cgp_ref_number": 123456789,
        "sinpe_ref": "SINPE987654",
        "status": "completed",
        "amount": {
          "value": 5000,
          "currency": "CRC",
          "formatted": "50.00 CRC"
        }
      }
    ]
  }
}
```
```
Tokens:
Raw