# pricing/top-countries

## Purpose
Returns the top countries with the best exchange rates and the payer that offers them for a given branch.
## When to Use
- Display optimal sending destinations based on best available rates
- Show a ranked list of countries with their best payer rates on a partner's interface

## How It Works
1. Send `branchId` as a query parameter
2. Authenticate with `x-client-id` and `x-secret-key` headers
3. Receive a ranked list of countries with best exchange rates

## Authentication
Requires `x-client-id` and `x-secret-key` headers. Partner must have `pricing/top-countries` in their allowed resources.
## Common Errors
- `400` Validation errors (missing branchId, invalid headers)
- `401` Invalid credentials
- `403` Access forbidden (endpoint not in partner resources)
- `422` Pricing data not available for the given parameters
- `500` Internal server error
- `502` Upstream service authentication failure
- `503` Service temporarily unavailable

<details><summary><b>Error codes (click to expand)</b></summary>
<table style='border-collapse:collapse; width:100%; margin-top:8px;'>
<thead><tr>
<th style='border:1px solid #e5e7eb; padding:6px; text-align:left;'>Code</th>
<th style='border:1px solid #e5e7eb; padding:6px; text-align:left;'>Description</th>
</tr></thead>
<tbody>
<tr><td style='border:1px solid #e5e7eb; padding:6px; width:140px;'><code>400001</code></td><td style='border:1px solid #e5e7eb; padding:6px;'>branchId is required</td></tr>
<tr><td style='border:1px solid #e5e7eb; padding:6px; width:140px;'><code>400005</code></td><td style='border:1px solid #e5e7eb; padding:6px;'>x-secret-key is required</td></tr>
<tr><td style='border:1px solid #e5e7eb; padding:6px; width:140px;'><code>400416</code></td><td style='border:1px solid #e5e7eb; padding:6px;'>The branchId is not valid for this partner</td></tr>
<tr><td style='border:1px solid #e5e7eb; padding:6px; width:140px;'><code>401000</code></td><td style='border:1px solid #e5e7eb; padding:6px;'>Invalid credentials</td></tr>
<tr><td style='border:1px solid #e5e7eb; padding:6px; width:140px;'><code>403001</code></td><td style='border:1px solid #e5e7eb; padding:6px;'>Access to this resource is forbidden for this client</td></tr>
<tr><td style='border:1px solid #e5e7eb; padding:6px; width:140px;'><code>422006</code></td><td style='border:1px solid #e5e7eb; padding:6px;'>Pricing data could not be retrieved</td></tr>
<tr><td style='border:1px solid #e5e7eb; padding:6px; width:140px;'><code>500000</code></td><td style='border:1px solid #e5e7eb; padding:6px;'>Internal server error</td></tr>
<tr><td style='border:1px solid #e5e7eb; padding:6px; width:140px;'><code>502001</code></td><td style='border:1px solid #e5e7eb; padding:6px;'>Unable to authenticate with upstream service</td></tr>
<tr><td style='border:1px solid #e5e7eb; padding:6px; width:140px;'><code>503001</code></td><td style='border:1px solid #e5e7eb; padding:6px;'>Service temporarily unavailable</td></tr>
</tbody></table></details>

Endpoint: GET /pricing/top-countries
Version: 1.0.0

## Query parameters:

  - `branchId` (string, required)
    Branch identifier for the partner. Must be a valid branch belonging to the partner's chain. Used to retrieve top-country rates for the specified branch.

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

  - `validations` (string)
    When set to 'true', returns the merged validation schema for this endpoint instead of executing the request.

Error codes: type=400002, allowedValues=400010

## Header parameters:

  - `x-client-id` (string, required)
    Unique identifier assigned to the integrating client. It determines the validation rules, allowed values, compliance policies, and operational limits applied to the request.

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

  - `x-secret-key` (string, required)
    Secret authentication key associated with the client. It is used to authorize the request and must be kept strictly confidential.

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

## Response 200 fields (application/json):

  - `status` (string)
    Response status indicator.

  - `data` (array)
    Array of top country objects sorted by best exchange rate.

  - `data.deliveryCountryISO` (string)
    ISO 3166-1 alpha-3 country code of the destination (e.g., MEX, COL, GTM).

  - `data.countryName` (string)
    Human-readable name of the destination country.

  - `data.deliveryLocationName` (string)
    Name of the payer/network offering the best rate for this country.

  - `data.deliveryMode` (string)
    Delivery mode code (e.g., P = Cash Pickup, T = Bank Deposit).

  - `data.exchangeRate` (number)
    Best available exchange rate for this country.

  - `data.deliveryAmountCurrencyISO` (string)
    ISO 4217 currency code of the delivery amount (e.g., MXN, COP).

## Response 400 fields (application/json):

  - `errors` (array)
    List of validation errors
Error catalog for 400 (click to expand)CodeDescription400001branchId is required400005x-secret-key is required400416The branchId is not valid for this partner

  - `errors.status` (string)
    Always 'failed'.

  - `errors.code` (integer)
    Internal error code.

  - `errors.message` (string)
    Human-readable error description.

  - `errors.details` (string)
    Field name or additional context.

## Response 401 fields (application/json):

  - `errors` (array)
    List of authentication errors
Error catalog for 401 (click to expand)CodeDescription401000Invalid credentials

  - `errors.status` (string)
    Always 'failed'.

  - `errors.code` (integer)
    Internal error code.

  - `errors.message` (string)
    Human-readable error description.

## Response 403 fields (application/json):

  - `errors` (array)
    List of authorization errors
Error catalog for 403 (click to expand)CodeDescription403001Access to this resource is forbidden for this client

  - `errors.status` (string)
    Always 'failed'.

  - `errors.code` (integer)
    Internal error code.

  - `errors.message` (string)
    Human-readable error description.

  - `errors.details` (string)
    Additional context.

## Response 422 fields (application/json):

  - `errors` (array)
    List of business rule errors
Error catalog for 422 (click to expand)CodeDescription422006Pricing data could not be retrieved

  - `errors.status` (string)
    Always 'failed'.

  - `errors.code` (integer)
    Internal error code.

  - `errors.message` (string)
    Human-readable error description.

## Response 500 fields (application/json):

  - `errors` (array)
    List of internal errors
Error catalog for 500 (click to expand)CodeDescription500000Internal server error or partner configuration error

  - `errors.status` (string)
    Always 'failed'.

  - `errors.code` (integer)
    Internal error code.

  - `errors.message` (string)
    Human-readable error description.

## Response 502 fields (application/json):

  - `errors` (array)
    List of upstream errors
Error catalog for 502 (click to expand)CodeDescription502001Unable to authenticate with pricing service

  - `errors.status` (string)
    Always 'failed'.

  - `errors.code` (integer)
    Internal error code.

  - `errors.message` (string)
    Human-readable error description.

## Response 503 fields (application/json):

  - `errors` (array)
    List of service availability errors
Error catalog for 503 (click to expand)CodeDescription503001Pricing service temporarily unavailable

  - `errors.status` (string)
    Always 'failed'.

  - `errors.code` (integer)
    Internal error code.

  - `errors.message` (string)
    Human-readable error description.