# pricing/payers

## Purpose
Retrieves available payers with their exchange rates and transaction limits for a given destination country and branch.
## When to Use
- Display available payout options and pricing to customers before they select a payer
- Show which payment networks are available in a destination country with their rate ranges
- Allow customers to compare payers by exchange rate and transaction limits

## How It Works
1. Send `branchId` and `deliveryCountryISO` as query parameters
2. Authenticate with `x-client-id` and `x-secret-key` headers
3. Receive a list of payers with rates and limits for the requested country

## Authentication
Requires `x-client-id` and `x-secret-key` headers. Partner must have `pricing/payers` in their allowed resources.
## Notes
- The `deliveryCountryISO` accepts ISO 3166-1 alpha-3 codes (e.g., MEX, COL, HND).
- Results include rate ranges and transaction amount limits per payer.

## Common Errors
- `400` Validation errors (missing branchId, missing deliveryCountryISO, 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>400009</code></td><td style='border:1px solid #e5e7eb; padding:6px;'>deliveryCountryISO 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/payers
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.

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

  - `deliveryCountryISO` (string, required)
    Destination country in ISO 3166-1 alpha-3 format (e.g., MEX, COL, HND, GTM).

You can retrieve the list of available countries from our Catalogs API:
[Catalogs Endpoint Countries](/apis/outbound/catalogs/paths/~1catalogs~1countries/get)

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

  - `validations` (string)
    Return validation schema instead of executing the request. When set to 'true', returns the merged schema (base + partner override) as JSON.

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 payer objects with rates and limits for the requested country.

  - `data.deliveryLocationName` (string)
    Name of the payer/network (e.g., Elektra, Bancolombia, Banrural).

  - `data.deliveryModeName` (string)
    Human-readable name of the delivery mode (e.g., CASH PICKUP, BANK DEPOSIT).

  - `data.deliveryAmountCurrencyName` (string)
    Name of the delivery currency (e.g., Peso Mexicano, Colombian Peso).

  - `data.exchangeRate` (number)
    Exchange rate offered by this payer.

  - `data.originationAmountFrom` (number)
    Minimum origination amount (USD) accepted for this payer.

  - `data.originationAmountTo` (number)
    Maximum origination amount (USD) accepted for this payer.

  - `data.fundingType` (string)
    Funding type applicable (e.g., CASH, ACH, CARD).

  - `data.sort` (integer)
    Sort order priority for display purposes.

  - `data.dolarAmountLimit` (number)
    Maximum dollar amount limit for this payer.

## Response 400 fields (application/json):

  - `errors` (array)
    List of validation errors
Error catalog for 400 (click to expand)CodeDescription400001branchId is required400005x-secret-key is required400009deliveryCountryISO 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.