Create Receiver

cURL

curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/receivers \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <api-key>' \
  --data '
{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "receiverType": "INDIVIDUAL",
  "email": "john.doe@example.com",
  "taxId": "RFC123456789",
  "firstName": "<string>",
  "lastName": "<string>",
  "dateOfBirth": "<string>",
  "businessName": "<string>",
  "dateOfConstitution": "<string>",
  "phoneNumber": "<string>",
  "isPep": true,
  "hasBeneficialOwner": true,
  "hasResourceProvider": true
}
'

import requests

url = "https://staging-api.capa.fi/api/partner/v2/receivers"

payload = {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "receiverType": "INDIVIDUAL",
    "email": "john.doe@example.com",
    "taxId": "RFC123456789",
    "firstName": "<string>",
    "lastName": "<string>",
    "dateOfBirth": "<string>",
    "businessName": "<string>",
    "dateOfConstitution": "<string>",
    "phoneNumber": "<string>",
    "isPep": True,
    "hasBeneficialOwner": True,
    "hasResourceProvider": True
}
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({
    userId: '550e8400-e29b-41d4-a716-446655440000',
    receiverType: 'INDIVIDUAL',
    email: 'john.doe@example.com',
    taxId: 'RFC123456789',
    firstName: '<string>',
    lastName: '<string>',
    dateOfBirth: '<string>',
    businessName: '<string>',
    dateOfConstitution: '<string>',
    phoneNumber: '<string>',
    isPep: true,
    hasBeneficialOwner: true,
    hasResourceProvider: true
  })
};

fetch('https://staging-api.capa.fi/api/partner/v2/receivers', 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/receivers",
  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([
    'userId' => '550e8400-e29b-41d4-a716-446655440000',
    'receiverType' => 'INDIVIDUAL',
    'email' => 'john.doe@example.com',
    'taxId' => 'RFC123456789',
    'firstName' => '<string>',
    'lastName' => '<string>',
    'dateOfBirth' => '<string>',
    'businessName' => '<string>',
    'dateOfConstitution' => '<string>',
    'phoneNumber' => '<string>',
    'isPep' => true,
    'hasBeneficialOwner' => true,
    'hasResourceProvider' => true
  ]),
  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/receivers"

	payload := strings.NewReader("{\n  \"userId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"receiverType\": \"INDIVIDUAL\",\n  \"email\": \"john.doe@example.com\",\n  \"taxId\": \"RFC123456789\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dateOfBirth\": \"<string>\",\n  \"businessName\": \"<string>\",\n  \"dateOfConstitution\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"isPep\": true,\n  \"hasBeneficialOwner\": true,\n  \"hasResourceProvider\": true\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/receivers")
  .header("partner-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"receiverType\": \"INDIVIDUAL\",\n  \"email\": \"john.doe@example.com\",\n  \"taxId\": \"RFC123456789\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dateOfBirth\": \"<string>\",\n  \"businessName\": \"<string>\",\n  \"dateOfConstitution\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"isPep\": true,\n  \"hasBeneficialOwner\": true,\n  \"hasResourceProvider\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging-api.capa.fi/api/partner/v2/receivers")

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  \"userId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"receiverType\": \"INDIVIDUAL\",\n  \"email\": \"john.doe@example.com\",\n  \"taxId\": \"RFC123456789\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dateOfBirth\": \"<string>\",\n  \"businessName\": \"<string>\",\n  \"dateOfConstitution\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"isPep\": true,\n  \"hasBeneficialOwner\": true,\n  \"hasResourceProvider\": true\n}"

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

{
  "success": true,
  "data": {
    "id": "9486244c-ff7d-4c22-9984-797179d7deaa",
    "userId": "1234567c-ff7d-4c22-9984-797179d7deaa",
    "receiverType": "INDIVIDUAL",
    "email": "john.doe@example.com",
    "disabled": false,
    "createdAt": "2024-04-05T13:45:27.063Z",
    "updatedAt": "2024-04-05T13:45:27.063Z"
  }
}

POST

api

partner

receivers

cURL

curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/receivers \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <api-key>' \
  --data '
{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "receiverType": "INDIVIDUAL",
  "email": "john.doe@example.com",
  "taxId": "RFC123456789",
  "firstName": "<string>",
  "lastName": "<string>",
  "dateOfBirth": "<string>",
  "businessName": "<string>",
  "dateOfConstitution": "<string>",
  "phoneNumber": "<string>",
  "isPep": true,
  "hasBeneficialOwner": true,
  "hasResourceProvider": true
}
'

import requests

url = "https://staging-api.capa.fi/api/partner/v2/receivers"

payload = {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "receiverType": "INDIVIDUAL",
    "email": "john.doe@example.com",
    "taxId": "RFC123456789",
    "firstName": "<string>",
    "lastName": "<string>",
    "dateOfBirth": "<string>",
    "businessName": "<string>",
    "dateOfConstitution": "<string>",
    "phoneNumber": "<string>",
    "isPep": True,
    "hasBeneficialOwner": True,
    "hasResourceProvider": True
}
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({
    userId: '550e8400-e29b-41d4-a716-446655440000',
    receiverType: 'INDIVIDUAL',
    email: 'john.doe@example.com',
    taxId: 'RFC123456789',
    firstName: '<string>',
    lastName: '<string>',
    dateOfBirth: '<string>',
    businessName: '<string>',
    dateOfConstitution: '<string>',
    phoneNumber: '<string>',
    isPep: true,
    hasBeneficialOwner: true,
    hasResourceProvider: true
  })
};

fetch('https://staging-api.capa.fi/api/partner/v2/receivers', 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/receivers",
  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([
    'userId' => '550e8400-e29b-41d4-a716-446655440000',
    'receiverType' => 'INDIVIDUAL',
    'email' => 'john.doe@example.com',
    'taxId' => 'RFC123456789',
    'firstName' => '<string>',
    'lastName' => '<string>',
    'dateOfBirth' => '<string>',
    'businessName' => '<string>',
    'dateOfConstitution' => '<string>',
    'phoneNumber' => '<string>',
    'isPep' => true,
    'hasBeneficialOwner' => true,
    'hasResourceProvider' => true
  ]),
  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/receivers"

	payload := strings.NewReader("{\n  \"userId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"receiverType\": \"INDIVIDUAL\",\n  \"email\": \"john.doe@example.com\",\n  \"taxId\": \"RFC123456789\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dateOfBirth\": \"<string>\",\n  \"businessName\": \"<string>\",\n  \"dateOfConstitution\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"isPep\": true,\n  \"hasBeneficialOwner\": true,\n  \"hasResourceProvider\": true\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/receivers")
  .header("partner-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"receiverType\": \"INDIVIDUAL\",\n  \"email\": \"john.doe@example.com\",\n  \"taxId\": \"RFC123456789\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dateOfBirth\": \"<string>\",\n  \"businessName\": \"<string>\",\n  \"dateOfConstitution\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"isPep\": true,\n  \"hasBeneficialOwner\": true,\n  \"hasResourceProvider\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging-api.capa.fi/api/partner/v2/receivers")

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  \"userId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"receiverType\": \"INDIVIDUAL\",\n  \"email\": \"john.doe@example.com\",\n  \"taxId\": \"RFC123456789\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dateOfBirth\": \"<string>\",\n  \"businessName\": \"<string>\",\n  \"dateOfConstitution\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"isPep\": true,\n  \"hasBeneficialOwner\": true,\n  \"hasResourceProvider\": true\n}"

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

{
  "success": true,
  "data": {
    "id": "9486244c-ff7d-4c22-9984-797179d7deaa",
    "userId": "1234567c-ff7d-4c22-9984-797179d7deaa",
    "receiverType": "INDIVIDUAL",
    "email": "john.doe@example.com",
    "disabled": false,
    "createdAt": "2024-04-05T13:45:27.063Z",
    "updatedAt": "2024-04-05T13:45:27.063Z"
  }
}

Creates a receiver for third-party payments. Receivers represent individuals or businesses who can receive funds through off-ramp or cross-ramp transactions on behalf of a user.

Field Relationships

Set receiverType to INDIVIDUAL or BUSINESS — this determines which fields are required.
INDIVIDUAL requires: firstName, lastName, countryOfBirth.
BUSINESS requires: businessName, countryOfConstitution.
pepInfo is required only when isPep is true.

Use Cases

Third-party payments: Create receivers so users can send off-ramp payouts to other individuals or businesses.
Payroll: Set up employees or contractors as receivers for automated payouts.

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”
400	`BAD_REQUEST`	”Provided email is not valid”
500	`RECEIVER_CREATION_FAILED`	”Failed to create receiver. Please try again later.”

Authorizations

partner-api-key

string

header

required

API key for the affiliated partner performing the request.

Body

application/json

userId

string

required

User ID who owns this receiver

Example:

"550e8400-e29b-41d4-a716-446655440000"

receiverType

enum<string>

required

Type of receiver (INDIVIDUAL or BUSINESS)

Available options:

INDIVIDUAL,

BUSINESS

Example:

"INDIVIDUAL"

string

required

Email address of the receiver

Example:

"john.doe@example.com"

taxId

string

required

Tax identification number

Example:

"RFC123456789"

firstName

string

First name (required for INDIVIDUAL)

lastName

string

Last name (required for INDIVIDUAL)

countryOfBirth

enum<string>

Country of birth (required for INDIVIDUAL)

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

dateOfBirth

string

Date of birth (ISO date format)

businessName

string

Legal name (required for BUSINESS)

countryOfConstitution

enum<string>

Country of constitution (required for BUSINESS)

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

dateOfConstitution

string

Date of constitution (ISO date format)

phoneNumber

string

Phone number

isPep

boolean

Whether the receiver is a Politically Exposed Person

hasBeneficialOwner

boolean

Declaration of beneficial owner existence

hasResourceProvider

boolean

Declaration of resource provider existence

Response

Receiver created successfully. Returns the receiver details, including its id.

success

boolean

Example:

true

data

object

Show child attributes

Mock Testing Guide List Receivers

⌘I

​Field Relationships

​Use Cases

​Error Codes

​Common Errors

​User Ownership Errors

​Endpoint-Specific Errors

Authorizations

Body

Response

Field Relationships

Use Cases

Error Codes

Common Errors

User Ownership Errors

Endpoint-Specific Errors