수취인과 목적지

고객이 엔드포인트를 소유할 때는 고객 계좌를 사용하세요. 다른 사람이나 기업이 자금을 받을 때는 수취인과 목적지를 사용하세요. 수취인은 자금을 받는 대상을 기록해요. 목적지는 그들이 어디에서 받는지 기록해요.

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 요청 스키마에서 값을 선택하세요. other를 보내더라도 자유 입력 필드를 추가하지 마세요. Swipelux는 요청 스키마에 정의되지 않은 필드를 무시하므로 해당 텍스트는 저장되지 않아요. 법정화폐 목적지를 생성하기 전에 주소를 포함하세요. 반환된 수취인 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 키로 지급해요. Pix 키로는 숫자만으로 된 CPF 또는 CNPJ, +55 뒤에 10자리 또는 11자리 숫자가 오는 전화번호, 이메일, 랜덤 키를 사용할 수 있어요. Pix Safe 목적지는 taxId의 예금주 CPF 또는 CNPJ, bankCode의 8자리 은행 ISPB 코드, 지점, 검증 숫자를 포함한 계좌 번호로 식별되는 브라질 은행 계좌로 지급해요. 응답과 웹훅에서는 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. 목적지 준비 상태 대기