Recipient and destination use cases

const recipient = await post('/v1/transfer-recipients', {
  type: 'individual',
  displayName: payee.name,
  firstName: payee.firstName,
  lastName: payee.lastName,
  relationship: 'contractor',
  email: payee.email,
  address: { line1: payee.line1, city: payee.city, country: payee.country },
});

await post(`/v1/transfer-recipients/${recipient.id}/payment-details`, {
  routeId: route.id,
  currency: route.destinationCurrency,
  country: payee.country,
  accountHolderName: payee.name,
  fields: collectedFromDescriptors,     // see routing fields and verification
  isDefault: true,
});

await store(payee.id, recipient.id);    // your join, kept on your side

for (const payee of run.payees) {
  const destination = await post(`/v1/transfer-destinations/recipients/${payee.recipientId}`, {});

  if (destination.displayName !== payee.expectedAccountName) {
    // Verification returned a different name than we hold. Stop and review;
    // this is the cheapest fraud and typo check available.
    await flagForReview(payee, destination.displayName);
    continue;
  }

  await post('/v1/transfers', {
    destinationId: destination.id,
    externalReference: `payroll_${run.id}_${payee.id}`,
    // …amounts
  });

  await pace();   // 120/min covers destinations and transfers together
}

curl --request POST \
  --url "$SAKAWAVE_BASE_URL/v1/transfer-destinations" \
  --header "Authorization: Bearer $SAKAWAVE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "external",
    "routeId": "01K2Z3AB4M5N6P7Q8RSTVWXYZA",
    "currency": "KES",
    "country": "KE",
    "accountName": "Ada Okafor",
    "recipientRelationship": "customer",
    "recipientEmail": "ada@example.com",
    "recipientAddressLine1": "14 Marina Road",
    "recipientCity": "Nairobi",
    "bankCode": "001",
    "accountNumber": "0123456789"
  }'

// Your own account. Not a customer wallet — those are excluded.
{ "type": "own_account", "accountId": "01K2Z3AB4D5E6F7G8H9JKMNPQR", "currency": "NGN" }

// Any Sakawave account by its public handle, including customer wallets.
{ "type": "sakawave_tag", "tag": "AA0271849366" }

{ "statusCode": 404, "message": "Destination account not found.", "code": "destination_account_not_found" }

// 1. Add the new detail and make it the default.
const replacement = await post(`/v1/transfer-recipients/${recipientId}/payment-details`, {
  routeId: newRoute.id,
  currency: newRoute.destinationCurrency,
  country: payee.country,
  accountHolderName: payee.name,
  fields: newFields,
  isDefault: true,
});

// 2. Prove it resolves before discarding the old one.
const destination = await post(`/v1/transfer-destinations/recipients/${recipientId}`, {
  paymentDetailId: replacement.id,
});
if (destination.displayName !== payee.expectedAccountName) throw new Error('verification mismatch');

// 3. Only now remove the old detail.
await del(`/v1/transfer-recipients/${recipientId}/payment-details/${oldDetailId}`);

curl --request DELETE \
  --url "$SAKAWAVE_BASE_URL/v1/transfer-recipients/$RECIPIENT_ID" \
  --header "Authorization: Bearer $SAKAWAVE_API_KEY"