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:
| Rail | Use it when you have | Bank name needed | Beneficiary tax ID needed |
|---|---|---|---|
PY_ACCOUNT_ID_TRANSFER | An alias: cédula (CI), RUC, phone number or email | No | No |
PY_LOCAL_TRANSFER | A local bank account number | Yes | Yes |
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 type | Format |
|---|---|
| CI | Cédula de identidad, 4 to 8 digits |
| RUC | Valid RUC, digits only and including its check digit |
| Phone | International format starting with +595 |
| A valid email address |
Required fields for this option:
| Field | Description |
|---|---|
currency | PYG |
amount | Amount in PYG |
destination.rail | PY_ACCOUNT_ID_TRANSFER |
destination.country | PY |
destination.accountIdentifierValue | CI, RUC, phone or email |
destination.beneficiary.name | Account holder name |
destination.beneficiary.country | PY |
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 as0981123456are 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:
| Field | Description |
|---|---|
currency | PYG |
amount | Amount in PYG |
destination.rail | PY_LOCAL_TRANSFER |
destination.country | PY |
destination.accountIdentifierValue | Bank account number |
destination.institution.name | Bank name |
destination.beneficiary.name | Account holder name |
destination.beneficiary.taxId | Account holder cédula (CI) or RUC |
destination.beneficiary.country | PY |
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¤cy=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
idor 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
| Event | Effect on Balance |
|---|---|
| Transfer created | amountInUSD is immediately deducted from the user's available balance |
| Transfer rejected | Amount 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.