Once a customer has completed the KYC requirements in the contextual country, the next step is to attach a payment method.

To add the customer's FIAT bank account, simply call the Create Payment Method endpoint.

To view a list of the required fields to add a payment method, use the List Payment Methods Requirements endpoint.

Best Practices

Always ensure the customer has completed KYC/KYB verification before adding a payment method.

Use the List Payment Method Requirements endpoint to dynamically retrieve required fields by country.

Validate bank account formats before submitting requests to reduce errors.

Store payment method identifiers securely, as they will be required when initiating transactions.

Mexico

Field	Value
type	SPEI
accountNumber	18 Digit Account Number
accountType	CLABE

Brazil

Field	Value
type	PIX
accountNumber	11 Digit Account Number
accountType	CPF

Argentina

Field	Value
type	COELSA
accountNumber	22 Digit Account Number
accountType	CVU \| CBU

In the case of Alias being used for account type:

Field	Description	Rules
Alias	Unique identifier for the virtual account.	Allowed characters in account number: letters (a–z, A–Z), numbers (0–9), hyphen (-), and dot (.) Length: 6 to 20 characters Must be unique across the system

⚠️ Note: The alias can only be modified once every 24 hours.

Colombia

Field	Value
type	ACH
accountNumber	10 or 11 Digit Account Number
accountType	AHORRO \| NEQUI
accountName	Bancamia

China/HK

Field	Value	Description
CustomerID	String	UUID
type	BANK_CN	Account type (BANK_CN)
fiatAccountFields	Object	Bank account details
accountNumber	String	Account number
accountType	String	Account Type
bankStreet	String	Bank Address
bankCity	String	Bank City
bankState	String	Bank State
bankPostalCode	String	Postal Code
networkIdentifier	String	SWIFT Code or Bank identifier
accountName	String	Account Name (Bank holding the account)

USA

Field	Value	Description
CustomerID	String	UUID
type	BANK_CN	Account type (BANK_CN)
fiatAccountFields	Object	Bank account details
accountNumber	String	Account number
accountType	String	Account Type
bankStreet	String	Bank Address
bankCity	String	Bank City
bankState	String	Bank State
bankPostalCode	String	Postal Code

External Fiat Accounts Creation (isExternal: true) - Complete Documentation

This documentation contains all the cURL commands necessary to create external bank accounts (isExternal: true) in the development environment (restricted-dev) for each supported country, using the API POST /fiatAccounts.

🇦🇷 Argentina (AR): COELSA

Type: COELSA

AccountType Variants:

1. CBU (Clave Bancaria Uniforme)

Identifier: CBU (22 digits, e.g. 0290013110000576749489)

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "COELSA",
  "fiatAccountFields": {
    "accountNumber": "0290013110000576749489",
    "accountType": "CBU"
  },
  "isExternal": true
}'

2. CVU (Clave Virtual Uniforme)

Identifier: CVU (22 digits, e.g. 0000003100054854230351)

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "COELSA",
  "fiatAccountFields": {
    "accountNumber": "0000003100054854230351",
    "accountType": "CVU"
  },
  "isExternal": true
}'

3. ALIAS

Identifier: ALIAS (6-20 alphanumeric characters, e.g. alias.test123)

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "COELSA",
  "fiatAccountFields": {
    "accountNumber": "alias.test123",
    "accountType": "ALIAS"
  },
  "isExternal": true
}'

Note: For Argentina, isExternal is automatically determined by comparing the customer's DNI with the bank's DNI. If they are different, it is marked as isExternal: true. No additional fields are required in metadata.

🇧🇷 Brazil (BR): PIX

Type: PIX

AccountType Variants:

1. EMAIL

Identifier: EMAIL (e.g. [email protected]) Required Metadata: documentNumber, accountHolderName

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "PIX",
  "fiatAccountFields": {
    "accountNumber": "[email protected]",
    "accountType": "EMAIL",
    "metadata": {
      "documentNumber": "12312312",
      "accountHolderName": "Da Silva"
    }
  },
  "isExternal": true
}'

2. PHONE

Identifier: PHONE (Brazilian phone number, e.g. +5511999999999) Required Metadata: documentNumber, accountHolderName

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "PIX",
  "fiatAccountFields": {
    "accountNumber": "+5511999999999",
    "accountType": "PHONE",
    "metadata": {
      "documentNumber": "12345678901",
      "accountHolderName": "João Silva"
    }
  },
  "isExternal": true
}'

3. CPF

Identifier: CPF (11 digits, e.g. 12345678901) Required Metadata: documentNumber, accountHolderName

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "PIX",
  "fiatAccountFields": {
    "accountNumber": "12345678901",
    "accountType": "CPF",
    "metadata": {
      "documentNumber": "12345678901",
      "accountHolderName": "Maria Santos"
    }
  },
  "isExternal": true
}'

4. EVP (Chave Aleatória)

Identifier: EVP (UUID, e.g. 550e8400-e29b-41d4-a716-446655440000) Required Metadata: documentNumber, accountHolderName

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "PIX",
  "fiatAccountFields": {
    "accountNumber": "550e8400-e29b-41d4-a716-446655440000",
    "accountType": "EVP",
    "metadata": {
      "documentNumber": "12345678901",
      "accountHolderName": "Carlos Oliveira"
    }
  },
  "isExternal": true
}'

🇧🇴 Bolivia (BOL): ACH_BOL

Type: ACH_BOL

AccountType Variants:

1. ACCOUNT_NUMBER

Identifier: Account Number (e.g. 2502466368) Required Metadata: accountHolderName, documentNumber, accountHolderLastName, email Additional Fields: accountBankCode (e.g. BNB0)

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
   "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
   "type": "ACH_BOL",
   "fiatAccountFields": {
      "accountNumber": "2502466368",
      "accountBankCode": "BANCO_GANADERO",
      "accountType": "CHECKING",
      "metadata": {
        "accountHolderName": "Luis",
        "accountHolderLastName": "Morales",
        "documentNumber": "12312312",
        "email": "[email protected]"
      }
   },
   "isExternal": true
}'

Note: Bolivia does not specifically validate accountType in the code, but uses ACCOUNT_NUMBER as the standard type.

🇨🇴 Colombia (CO): ACH

Type: ACH

AccountType Variants:

1. CORRIENTE

Identifier: Checking Account Number (e.g. 51600008149) Required Metadata: accountHolderName, documentType, documentNumber Additional Fields: accountName (bank name, e.g. Bancolombia)

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "ACH",
  "fiatAccountFields": {
    "accountNumber": "51600008149",
    "accountType": "CORRIENTE",
    "accountName": "Bancolombia",
    "metadata": {
      "accountHolderName": "Test",
      "documentType": "CC",
      "documentNumber": "1234567890"
    }
  },
  "isExternal": true
}'

2. AHORRO

Identifier: Savings Account Number (e.g. 51600008149) Required Metadata: accountHolderName, documentType, documentNumber Additional Fields: accountName (bank name, e.g. Bancolombia)

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "ACH",
  "fiatAccountFields": {
    "accountNumber": "51600008149",
    "accountType": "AHORRO",
    "accountName": "Bancolombia",
    "metadata": {
      "accountHolderName": "Test",
      "documentType": "CC",
      "documentNumber": "1234567890"
    }
  },
  "isExternal": true
}'

3. NEQUI

Identifier: Nequi Number (10-11 digits, e.g. 3001234567) Required Metadata: accountHolderName, documentType, documentNumber

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "ACH",
  "fiatAccountFields": {
    "accountNumber": "3001234567",
    "accountType": "NEQUI",
    "metadata": {
      "accountHolderName": "Juan Pérez",
      "documentType": "CC",
      "documentNumber": "1234567890"
    }
  },
  "isExternal": true
}'

Note: For CORRIENTE and AHORRO, the accountName field is mandatory and must exactly match the name of a supported bank.

🇩🇴 Dominican Republic (DO): ACH_DOM

Type: ACH_DOM

AccountType Variants:

1. CORRIENTE

Identifier: Checking Account Number (e.g. 9608006794) Required Metadata: accountHolderName, documentType, documentNumber, email Additional Fields: accountName (bank name, e.g. BANCO DE RESERVAS DE LA R.D)

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "ACH_DOM",
  "fiatAccountFields": {
    "accountNumber": "9608006794",
    "accountType": "CORRIENTE",
    "accountName": "BANCO DE RESERVAS DE LA R.D",
    "metadata": {
      "accountHolderName": "Rafael Trujillo",
      "documentType": "National ID",
      "documentNumber": "12312312",
      "email": "[email protected]"
    }
  },
  "isExternal": true
}'

2. AHORRO

Identifier: Savings Account Number (e.g. 9608006794) Required Metadata: accountHolderName, documentType, documentNumber, email Additional Fields: accountName (bank name, e.g. BANCO DE RESERVAS DE LA R.D)

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "ACH_DOM",
  "fiatAccountFields": {
    "accountNumber": "9608006794",
    "accountType": "AHORRO",
    "accountName": "BANCO DE RESERVAS DE LA R.D",
    "metadata": {
      "accountHolderName": "Rafael Trujillo",
      "documentType": "National ID",
      "documentNumber": "12312312",
      "email": "[email protected]"
    }
  },
  "isExternal": true
}'

🇲🇽 Mexico (MX): SPEI

Type: SPEI

AccountType Variants:

1. CLABE

Identifier: CLABE (18 digits, e.g. 072180465644370317) Required Metadata: accountHolderName

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "SPEI",
  "fiatAccountFields": {
    "accountNumber": "072180465644370317",
    "accountType": "CLABE",
    "metadata": {
      "accountHolderName": "Porfirio Díaz"
    }
  },
  "isExternal": true
}'

🇨🇱 Chile (CL): ACH_CHL

Type: ACH_CHL

AccountType Variants:

1. CHECKING

Identifier: Checking Account Number (e.g. 12312312335) Required Metadata: accountHolderName, email, documentNumber (RUT), accountHolderLastName Additional Fields: accountBankCode (bank code, e.g. 0001)

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "ACH_CHL",
  "fiatAccountFields": {
    "accountNumber": "12312312335",
    "accountType": "CHECKING",
    "accountBankCode": "BANCODELESTADODECHILE",
    "metadata": {
      "accountHolderName": "Augusto",
      "accountHolderLastName": "Monasterios",
      "email": "[email protected]",
      "documentNumber": "12.345.678-9"
    }
  },
  "isExternal": true
}'

2. SAVING

Identifier: Savings Account Number (e.g. 12312312335) Required Metadata: accountHolderName, email, documentNumber (RUT) Additional Fields: accountBankCode (bank code, e.g. 0001)

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "ACH_CHL",
  "fiatAccountFields": {
    "accountNumber": "12312312335",
    "accountType": "SAVING",
    "accountBankCode": "0001",
    "metadata": {
      "accountHolderName": "Augusto Monasterios",
      "email": "[email protected]",
      "documentNumber": "12.345.678-9"
    }
  },
  "isExternal": true
}'

🇵🇪 Peru (PE): ACH_PER

Type: ACH_PER

AccountType Variants:

1. CORRIENTE

Identifier: Checking Account Number (7-17 digits, e.g. 51600008149) Required Metadata: accountHolderName, accountHolderLastName, documentNumber, phoneNumber, bankCity, documentType, bankAddress, email
Additional Fields: accountName (bank code, must match type_id of supported banks)

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "ACH_PER",
  "fiatAccountFields": {
    "accountNumber": "51600008149",
    "accountType": "CORRIENTE",
    "accountName": "001",
    "metadata": {
      "accountHolderName": "Juan",
      "accountHolderLastName": "Pérez",
      "documentNumber": "12345678",
      "phoneNumber": "+51987654321",
      "bankCity": "Lima",
      "documentType": "DNI",
      "bankAddress": "Av. Principal 123",
      "email": "[email protected]"
    }
  },
  "isExternal": true
}'

2. AHORRO

Identifier: Savings Account Number (7-14 digits, e.g. 51600008149) Required Metadata: accountHolderName, accountHolderLastName, documentNumber, phoneNumber, bankCity, documentType, bankAddress Additional Fields: accountName (bank code, must match type_id of supported banks)

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
  "customerId": "042cc6b4-6774-45b4-a686-95a0e7b1b8be",
  "type": "ACH_PER",
  "fiatAccountFields": {
    "accountNumber": "51600008149",
    "accountType": "AHORRO",
    "accountName": "001",
    "metadata": {
      "accountHolderName": "Juan",
      "accountHolderLastName": "Pérez",
      "documentNumber": "12345678",
      "phoneNumber": "+51987654321",
      "bankCity": "Lima",
      "documentType": "DNI",
      "bankAddress": "Av. Principal 123"
    }
  },
  "isExternal": true
}'

Note: Valid values for documentType in Peru are: DNI, PASAPORTE, CE, RUC, SOCIAL SEC.

🇺🇸 United States (US): BANK_USA

Type: BANK_USA

AccountType Variants:

1. CHECKING

Identifier: Checking Account Number (8-34 digits, e.g. 123456789012) Required Metadata: bankStreet, bankCity, bankState, bankPostalCode, bankCountry (bank address)

Additional Required Fields:

accountName (bank name)
routingNumber (routing number)

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
   "customerId":"042cc6b4-6774-45b4-a686-95a0e7b1b8be",
   "type":"BANK_USA",
   "fiatAccountFields":{
      "accountNumber":"000003020000",
      "accountType":"CHECKING",
      "routingNumber":"00000000",
      "accountName":"Example Bank",
      "metadata":{
         "bankStreet":"1801 example ST",
         "bankCity":"Kansas City",
         "bankState":"Missouri",
         "bankPostalCode":"1231",
         "bankCountry":"USA"
      }
   },
   "isExternal":true
}

2. SAVING

Identifier: Savings Account Number (8-34 digits, e.g. 123456789012) Required Metadata: bankStreet, bankCity, bankState, bankPostalCode, bankCountry (bank address)

Additional Required Fields:

accountName (bank name)
routingNumber (routing number)

curl --request POST \
  --url https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts \
  --header 'Content-Type: application/json' \
  --header 'accept: /' \
  --header 'api-key: alfredpay' \
  --header 'api-secret: hLacEq' \
  --data '{
   "customerId":"042cc6b4-6774-45b4-a686-95a0e7b1b8be",
   "type":"BANK_USA",
   "fiatAccountFields":{
      "accountNumber":"000003020000",
      "accountType":"SAVING",
      "routingNumber":"00000000",
      "accountName":"Example Bank",
      "metadata":{
         "bankStreet":"1801 example ST",
         "bankCity":"Kansas City",
         "bankState":"Missouri",
         "bankPostalCode":"1231",
         "bankCountry":"USA"
      }
   },
   "isExternal":true
}

Account Type Summary by Country

Country	Type	Valid accountTypes
🇦🇷 Argentina	COELSA	`CBU`, `CVU`, `ALIAS`
🇧🇷 Brazil	PIX	`EMAIL`, `PHONE`, `CPF`, `EVP`
🇧🇴 Bolivia	ACH_BOL	`ACCOUNT_NUMBER`
🇨🇴 Colombia	ACH	`CORRIENTE`, `AHORRO`, `NEQUI`
🇩🇴 Dominican Republic	ACH_DOM	`CORRIENTE`, `AHORRO`
🇲🇽 Mexico	SPEI	`CLABE`
🇨🇱 Chile	ACH_CHL	`CHECKING`, `SAVING`
🇵🇪 Peru	ACH_PER	`CORRIENTE`, `AHORRO`
🇺🇸 United States	BANK_USA	`CHECKING`, `SAVING`

Important Notes

Argentina (COELSA): The isExternal field is automatically determined by comparing the customer's DNI with the bank's DNI. No additional fields are required in metadata.
Brazil (PIX): All types require documentNumber and accountHolderName in metadata.
Colombia (ACH): For CORRIENTE and AHORRO, the accountName field is mandatory and must exactly match the name of a supported bank.
Dominican Republic (ACH_DOM): Requires email in metadata in addition to other fields.
Chile (ACH_CHL): Requires email and documentNumber (RUT) in metadata.
Peru (ACH_PER): Requires multiple fields in metadata including accountHolderLastName, phoneNumber, bankCity, documentType, bankAddress, and email (for CORRIENTE only).
United States (BANK_USA): Register under metadata bankStreet, bankCity, bankState, bankPostalCode, bankCountry & bank address
Bolivia (ACH_BOL): Requires accountBankCode in addition to metadata. Does not require accountType field.

Endpoint

POST https://penny-api-restricted-dev.alfredpay.io/api/v1/third-party-service/penny/fiatAccounts

Headers

Content-Type: application/json
accept: /
api-key: alfredpay
api-secret: hLacEq