Add Bank Account (Receiver)

cURL

curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/banks/receivers/{receiverId}/accounts \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <api-key>' \
  --data '
{
  "accountIdentifier": "014680260346007120",
  "country": "MX",
  "bankName": "<string>",
  "documentIdentifier": "<string>",
  "routingNumber": "<string>",
  "bic": "<string>",
  "iban": "<string>",
  "alias": "My savings"
}
'

import requests

url = "https://staging-api.capa.fi/api/partner/v2/banks/receivers/{receiverId}/accounts"

payload = {
    "accountIdentifier": "014680260346007120",
    "country": "MX",
    "bankName": "<string>",
    "documentIdentifier": "<string>",
    "routingNumber": "<string>",
    "bic": "<string>",
    "iban": "<string>",
    "alias": "My savings"
}
headers = {
    "partner-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'partner-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountIdentifier: '014680260346007120',
    country: 'MX',
    bankName: '<string>',
    documentIdentifier: '<string>',
    routingNumber: '<string>',
    bic: '<string>',
    iban: '<string>',
    alias: 'My savings'
  })
};

fetch('https://staging-api.capa.fi/api/partner/v2/banks/receivers/{receiverId}/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging-api.capa.fi/api/partner/v2/banks/receivers/{receiverId}/accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'accountIdentifier' => '014680260346007120',
    'country' => 'MX',
    'bankName' => '<string>',
    'documentIdentifier' => '<string>',
    'routingNumber' => '<string>',
    'bic' => '<string>',
    'iban' => '<string>',
    'alias' => 'My savings'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "partner-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://staging-api.capa.fi/api/partner/v2/banks/receivers/{receiverId}/accounts"

	payload := strings.NewReader("{\n  \"accountIdentifier\": \"014680260346007120\",\n  \"country\": \"MX\",\n  \"bankName\": \"<string>\",\n  \"documentIdentifier\": \"<string>\",\n  \"routingNumber\": \"<string>\",\n  \"bic\": \"<string>\",\n  \"iban\": \"<string>\",\n  \"alias\": \"My savings\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("partner-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://staging-api.capa.fi/api/partner/v2/banks/receivers/{receiverId}/accounts")
  .header("partner-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"accountIdentifier\": \"014680260346007120\",\n  \"country\": \"MX\",\n  \"bankName\": \"<string>\",\n  \"documentIdentifier\": \"<string>\",\n  \"routingNumber\": \"<string>\",\n  \"bic\": \"<string>\",\n  \"iban\": \"<string>\",\n  \"alias\": \"My savings\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging-api.capa.fi/api/partner/v2/banks/receivers/{receiverId}/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["partner-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"accountIdentifier\": \"014680260346007120\",\n  \"country\": \"MX\",\n  \"bankName\": \"<string>\",\n  \"documentIdentifier\": \"<string>\",\n  \"routingNumber\": \"<string>\",\n  \"bic\": \"<string>\",\n  \"iban\": \"<string>\",\n  \"alias\": \"My savings\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "id": "string",
    "userId": "string",
    "partnerId": "string",
    "bankName": "string",
    "accountNumber": "string",
    "accountType": "SAVINGS",
    "clabe": "string",
    "country": "MX",
    "rampType": "ON_RAMP",
    "documentNumber": "string",
    "documentType": "PASSPORT",
    "alias": "string",
    "isVerified": true,
    "verificationStatus": "PENDING",
    "verifiedAt": null,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

POST

api

partner

banks

receivers

{receiverId}

accounts

cURL

curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/banks/receivers/{receiverId}/accounts \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <api-key>' \
  --data '
{
  "accountIdentifier": "014680260346007120",
  "country": "MX",
  "bankName": "<string>",
  "documentIdentifier": "<string>",
  "routingNumber": "<string>",
  "bic": "<string>",
  "iban": "<string>",
  "alias": "My savings"
}
'

import requests

url = "https://staging-api.capa.fi/api/partner/v2/banks/receivers/{receiverId}/accounts"

payload = {
    "accountIdentifier": "014680260346007120",
    "country": "MX",
    "bankName": "<string>",
    "documentIdentifier": "<string>",
    "routingNumber": "<string>",
    "bic": "<string>",
    "iban": "<string>",
    "alias": "My savings"
}
headers = {
    "partner-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'partner-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountIdentifier: '014680260346007120',
    country: 'MX',
    bankName: '<string>',
    documentIdentifier: '<string>',
    routingNumber: '<string>',
    bic: '<string>',
    iban: '<string>',
    alias: 'My savings'
  })
};

fetch('https://staging-api.capa.fi/api/partner/v2/banks/receivers/{receiverId}/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging-api.capa.fi/api/partner/v2/banks/receivers/{receiverId}/accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'accountIdentifier' => '014680260346007120',
    'country' => 'MX',
    'bankName' => '<string>',
    'documentIdentifier' => '<string>',
    'routingNumber' => '<string>',
    'bic' => '<string>',
    'iban' => '<string>',
    'alias' => 'My savings'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "partner-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://staging-api.capa.fi/api/partner/v2/banks/receivers/{receiverId}/accounts"

	payload := strings.NewReader("{\n  \"accountIdentifier\": \"014680260346007120\",\n  \"country\": \"MX\",\n  \"bankName\": \"<string>\",\n  \"documentIdentifier\": \"<string>\",\n  \"routingNumber\": \"<string>\",\n  \"bic\": \"<string>\",\n  \"iban\": \"<string>\",\n  \"alias\": \"My savings\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("partner-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://staging-api.capa.fi/api/partner/v2/banks/receivers/{receiverId}/accounts")
  .header("partner-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"accountIdentifier\": \"014680260346007120\",\n  \"country\": \"MX\",\n  \"bankName\": \"<string>\",\n  \"documentIdentifier\": \"<string>\",\n  \"routingNumber\": \"<string>\",\n  \"bic\": \"<string>\",\n  \"iban\": \"<string>\",\n  \"alias\": \"My savings\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging-api.capa.fi/api/partner/v2/banks/receivers/{receiverId}/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["partner-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"accountIdentifier\": \"014680260346007120\",\n  \"country\": \"MX\",\n  \"bankName\": \"<string>\",\n  \"documentIdentifier\": \"<string>\",\n  \"routingNumber\": \"<string>\",\n  \"bic\": \"<string>\",\n  \"iban\": \"<string>\",\n  \"alias\": \"My savings\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "id": "string",
    "userId": "string",
    "partnerId": "string",
    "bankName": "string",
    "accountNumber": "string",
    "accountType": "SAVINGS",
    "clabe": "string",
    "country": "MX",
    "rampType": "ON_RAMP",
    "documentNumber": "string",
    "documentType": "PASSPORT",
    "alias": "string",
    "isVerified": true,
    "verificationStatus": "PENDING",
    "verifiedAt": null,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Creates a new bank account for a user by receiver ID. Required fields vary by country — see the Off-Ramp bank requirements for details.

Error Codes

Common Errors

HTTP Status	Code	Message
401	`UNAUTHORIZED`	”API Key is missing”
401	`UNAUTHORIZED`	”Invalid API Key format”
401	`UNAUTHORIZED`	”Invalid API Key”
403	`INVALID_PARTNER_FLOW`	”The partner has an invalid flow.”

User Ownership Errors

HTTP Status	Code	Message
401	`UNAUTHORIZED`	”Partner information is required for this operation”
401	`UNAUTHORIZED`	”User is not associated with the partner”

Endpoint-Specific Errors

HTTP Status	Code	Message
400	`INVALID_USER_INPUT_ERROR`	”Invalid User Input”
404	`RECEIVER_NOT_FOUND`	”Receiver not found.”
400	`OFF_RAMP_USER_BANK_INFO_CREATION_FAILED`	”The provided bank is not currently supported.”
400	`USER_BANK_INFO_CREATION_FAILED`	”Failed to create user bank information.”

Authorizations

partner-api-key

string

header

required

API key for the affiliated partner performing the request.

Path Parameters

receiverId

string

required

The receiver ID to get bank info for

Example:

"8374f327-38bd-4b0b-b8a7-2524599eb903"

Body

application/json

accountIdentifier

string

required

Unique identifier for bank account. CLABE if country=MX.

Example:

"014680260346007120"

country

enum<string>

required

Country code. Determines validation rules.

Available options:

MX,

DO,

US,

AT,

BE,

BG,

HR,

CY,

CZ,

DK,

EE,

FI,

FR,

DE,

GR,

HU,

IE,

IT,

LV,

LT,

LU,

MT,

NL,

PL,

PT,

RO,

SK,

SI,

ES,

SE,

IS,

LI,

NO,

CH,

GB,

MC,

SM,

AD,

VA,

CN

Example:

"MX"

accountType

enum<string>

Account type. Required for DO.

Available options:

SAVINGS,

CHECKING

bankName

string

Bank name. Required for DO / US / SEPA. Not allowed for MX.

documentIdentifier

string

Document identifier. Required for DO, optional for MX.

documentType

enum<string>

Document type. Required for DO.

Available options:

PASSPORT,

CEDULA,

RNC

routingNumber

string

ABA routing number. Required for US.

address

object

Address. Required for US.

Show child attributes

accountHolder

object

Account holder info. Required for US & SEPA.

Show child attributes

bic

string

BIC code. Required for SEPA.

iban

string

IBAN. Required for SEPA.

alias

string

Optional friendly label for the bank account.

Example:

"My savings"

Response

Creates a new bank account for a user by receiverId. First gets the user by receiver ID, then creates the bank account.

success

boolean

Example:

true

data

object

Show child attributes

List Bank Accounts (Receiver)Delete Bank Account (Receiver)

⌘I

​Error Codes

​Common Errors

​User Ownership Errors

​Endpoint-Specific Errors

Authorizations

Path Parameters

Body

Response

Error Codes

Common Errors

User Ownership Errors

Endpoint-Specific Errors