Skip to main content

How to Create a PYG Bank Transfer

PYG bank transfers send funds to a Paraguayan bank account. The destination is a payout destination: the bank details (or account alias) and the beneficiary that owns them. You don't need to create anything beforehand: the destination is created automatically when you submit the transfer, or you can reuse one you already have.

There are two payment rails for Paraguay, and the one you pick decides which fields you need:

RailUse it when you haveBank name neededBeneficiary tax ID needed
PY_ACCOUNT_ID_TRANSFERAn alias: cédula (CI), RUC, phone number or emailNoNo
PY_LOCAL_TRANSFERA local bank account numberYesYes

You can create a PYG transfer in three ways:

  • Option A — New transfer using an account alias
  • Option B — New transfer with a local account number and bank name
  • Option C — Reuse a previously created payout destination with its id

PDF attachments are optional for PYG transfers. If included: maximum 10 files, maximum 1 MB per file, PDF format only.

Read the Bank Transfers Overview first for authentication, the request format and the transfer lifecycle.


Endpoint​

POST /payout/transfer

API Reference: Create a bank transfer

The request is multipart/form-data. The destination field is sent as a JSON-encoded string.


Option A — Alias​

Use rail PY_ACCOUNT_ID_TRANSFER. Pass the alias as accountIdentifierValue and the account holder name in beneficiary.name. The API detects which type of alias it is. No bank name is required.

Accepted aliases:

Alias typeFormat
CICédula de identidad, 4 to 8 digits
RUCValid RUC, digits only and including its check digit
PhoneInternational format starting with +595
EmailA valid email address

Required fields for this option:

FieldDescription
currencyPYG
amountAmount in PYG
destination.railPY_ACCOUNT_ID_TRANSFER
destination.countryPY
destination.accountIdentifierValueCI, RUC, phone or email
destination.beneficiary.nameAccount holder name
destination.beneficiary.countryPY

destination.label is optional and lets you find the destination later. Beneficiary type, taxId, address and email are optional for this rail.

Phone numbers must be sent in international format, for example +595981123456. Local formats such as 0981123456 are not accepted.

Request

curl -X POST "/api/v1/payout/transfer" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <token>" \
-F "currency=PYG" \
-F "amount=6400000" \
-F 'destination={"rail":"PY_ACCOUNT_ID_TRANSFER","country":"PY","accountIdentifierValue":"+595981123456","label":"Carlos - Phone alias","beneficiary":{"name":"Carlos Martínez","country":"PY"}}'

Option B — Local Account Number​

Use rail PY_LOCAL_TRANSFER. Pass the bank account number as accountIdentifierValue, the bank name in institution.name, and the account holder's name and cédula de identidad (or RUC) in the beneficiary.

Required fields for this option:

FieldDescription
currencyPYG
amountAmount in PYG
destination.railPY_LOCAL_TRANSFER
destination.countryPY
destination.accountIdentifierValueBank account number
destination.institution.nameBank name
destination.beneficiary.nameAccount holder name
destination.beneficiary.taxIdAccount holder cédula (CI) or RUC
destination.beneficiary.countryPY

The beneficiary type is optional: it is inferred from the tax ID.

Request

curl -X POST "/api/v1/payout/transfer" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <token>" \
-F "currency=PYG" \
-F "amount=6400000" \
-F 'destination={"rail":"PY_LOCAL_TRANSFER","country":"PY","accountIdentifierValue":"0011234567","institution":{"name":"Banco Continental"},"beneficiary":{"name":"Carlos Martínez","taxId":"4567890","country":"PY"}}'

Option C — Existing Payout Destination​

If a payout destination was created before, by a previous transfer or directly through the destinations API, reuse it by passing its id. No other destination fields are needed.

Find an existing Paraguayan destination

curl -X GET "/api/v1/payout-destination?country=PY&currency=PYG" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <token>"

This returns a paginated list of the active payout destinations of the authenticated user. Use the optional search parameter to look for a label or bank name, and use the id of the destination you want.

Request

curl -X POST "/api/v1/payout/transfer" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <token>" \
-F "currency=PYG" \
-F "amount=6400000" \
-F 'destination={"id":"d6c6c357-343f-4106-8f7d-b678c60ff10a"}'

Send either id or the destination fields, never both.


Attaching PDF files (optional)​

Add one -F "files=@..." part per file to any of the requests above.

-F "files=@invoice.pdf" \
-F "files=@transfer_order.pdf"

Response (201) — All options​

{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"type": "transfer",
"payoutNumber": "002095696342671878",
"status": "pending",
"currency": "PYG",
"amount": "6400000",
"amountInUSD": "1000.00",
"quote": "6400.00",
"pdfDocuments": [],
"destination": {
"id": "d6c6c357-343f-4106-8f7d-b678c60ff10a",
"label": "Carlos - Phone alias",
"rail": "PY_ACCOUNT_ID_TRANSFER",
"country": "PY",
"currency": "PYG",
"accountIdentifierScheme": "PY_ALIAS_PHONE",
"accountIdentifierValue": "+595981123456",
"beneficiary": {
"name": "Carlos Martínez"
}
},
"createdAt": "2026-05-14T12:05:00.000Z",
"updatedAt": "2026-05-14T12:05:00.000Z"
}

destination is a snapshot of the destination taken when the transfer was created. Later edits to the destination don't change it.


Balance Impact​

EventEffect on Balance
Transfer createdamountInUSD is immediately deducted from the user's available balance
Transfer rejectedAmount is automatically restored to the user's balance

amountInUSD and quote are calculated by the API from the current PYG exchange rate when the transfer is created.