收款方与目的地

当端点属于客户本人时,请使用客户账户。当另一个人或企业接收资金时,请使用收款方和目的地。收款方记录谁接收资金,目的地记录他们在哪里接收资金。

1. 创建收款方

使用 POST /v3/customers/{customerId}/recipients 创建个人或企业。请使用以下请求头:

Request headers

X-API-Key: ${SWIPELUX_API_KEY}
Idempotency-Key: recipient-create-001
Content-Type: application/json

Request body

{
  "type": "individual",
  "relationship": "contractor",
  "firstName": "Jason",
  "lastName": "Swipelux",
  "email": "jason@example.com",
  "phone": "+14155551234",
  "address": {
    "streetLine1": "1 Market Street",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "label": "Jason contractor"
}

relationship 描述收款方与你的客户之间的关系。请从 POST /v3/customers/{customerId}/recipients 请求 schema 中选择一个值。如果发送 other，不要添加配套的自由文本字段。Swipelux 会忽略请求 schema 未定义的字段，因此该文本不会被存储。在创建法币目的地之前,请包含地址。将返回的收款方 data.id 保存为 RECIPIENT_ID 并保留其当前状态。

2. 添加目的地

使用 POST /v3/customers/{customerId}/recipients/{recipientId}/destinations 创建端点。请为该目的地使用一个新的幂等键:

Request headers

X-API-Key: ${SWIPELUX_API_KEY}
Idempotency-Key: recipient-destination-create-001
Content-Type: application/json

银行目的地
Pix 目的地
Pix Safe 目的地
钱包目的地

{
  "type": "ach",
  "currency": "USD",
  "details": {
    "routingNumber": "021000021",
    "accountNumber": "123456789",
    "accountType": "checking",
    "bankName": "Example Bank",
    "accountHolderName": "Jason Swipelux",
    "country": "US"
  }
}

{
  "type": "pix",
  "currency": "BRL",
  "details": {
    "pixKey": "jason@example.com",
    "accountHolderName": "Jason Swipelux"
  }
}

{
  "type": "pix_safe",
  "currency": "BRL",
  "details": {
    "taxId": "52998224725",
    "bankCode": "00000208",
    "branchCode": "0001",
    "accountNumber": "123456-7",
    "accountType": "checking",
    "accountHolderName": "Jason Swipelux"
  }
}

{
  "type": "wallet",
  "currency": "USDC",
  "ownership": {
    "type": "self_custodied"
  },
  "details": {
    "network": "base",
    "address": "0x1111111111111111111111111111111111111111"
  }
}

Pix 和 Pix Safe 目的地接收 BRL，并需要客户已就绪的 Pix 能力（pix_pooled）。Pix 目的地向 Pix 密钥付款：仅含数字的 CPF 或 CNPJ、以 +55 开头后跟 10 位或 11 位数字的电话号码、电子邮件或随机密钥。Pix Safe 目的地向巴西银行账户付款，该账户通过 taxId 中持有人的 CPF 或 CNPJ、bankCode 中银行的 8 位 ISPB 代码、支行以及带校验位的账号来识别。响应和 webhook 返回的 taxId 会被掩码处理，仅显示最后四位。在您创建银行目的地时,Swipelux 会校验 IBAN、BIC、ABA 路由号码以及 CPF 或 CNPJ 号码等银行标识符,包括其校验和。格式错误的值会返回 400 validation_error。这些检查仅确认格式,并不能确认该账户是否存在或归谁所有。仅当收款方自行掌控该钱包时才使用 self_custodied。若钱包由其他托管方持有,请按照当前 API 参考中的对应变体填写。将返回的目的地 data.id 保存为 DESTINATION_ID 并保留其当前状态。

3. 等待目的地就绪

在创建报价之前,请读取 GET /v3/customers/{customerId}/recipients/{recipientId}/destinations/{destinationId}。仅当目的地当前的状态允许出金,并且其币种、方式和网络与预期的资金流转匹配时才继续。收款方和目的地的状态互相独立。在出金报价中使用 dst_ 开头的目的地 ID。rcp_ 开头的收款方 ID 用于标识所属人员/企业记录,并不是报价目的地。接下来,请携带已就绪的目的地前往发送资金。

开始使用

客户入驻

构建资金流

上线

收款方与目的地

1. 创建收款方

2. 添加目的地

3. 等待目的地就绪

​1. 创建收款方

​2. 添加目的地

​3. 等待目的地就绪

1. 创建收款方

2. 添加目的地

3. 等待目的地就绪