Envoyer des fonds

Chaque paiement commence à partir d’un portefeuille émis prêt et alimenté. Le modèle de destination dépend de qui détient l’endpoint.

Avant de commencer

Récupérez à nouveau le portefeuille source. Confirmez que son statut actuel autorise le paiement et que son solde disponible couvre le montant source prévu. Stockez son ID dérivé de la réponse en tant que SOURCE_WALLET_ID. Vous avez également besoin d’une capacité de paiement prête pour le client actuel et la destination sélectionnée. Les portefeuilles Tron existants peuvent envoyer des USDT vers un autre portefeuille Tron avec un devis stablecoin_transfers. L’entrée et la sortie doivent utiliser le même réseau et le même stablecoin. Vous ne pouvez pas créer de nouveaux portefeuilles émis sur Tron.

1. Préparer la destination

Propre
Tiers

Utilisez un compte bancaire externe détenu par le client lorsque le client détient l’endpoint. Créez-le avec POST /v3/customers/{customerId}/accounts et ces en-têtes :

Request headers

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

Request body

{
  "origin": "external",
  "type": "bank",
  "methods": ["ach", "wire"],
  "country": "US",
  "currency": "USD",
  "details": {
    "routingNumber": "021000021",
    "accountNumber": "123456789",
    "accountType": "checking",
    "bankName": "Example Bank",
    "accountHolderName": "Acme Payments SAS"
  },
  "label": "Customer operating account"
}

Lisez-le avec GET /v3/customers/{customerId}/accounts/{accountId}. Continuez uniquement lorsque son statut actuel autorise le paiement. Stockez son ID acc_ en tant que PAYOUT_DESTINATION_ID.

Créez la personne ou l’entreprise et son endpoint bancaire ou portefeuille via Destinataires et destinations. Continuez uniquement lorsque la destination est prête.Stockez l’ID dst_ renvoyé en tant que PAYOUT_DESTINATION_ID. N’utilisez pas l’ID rcp_ du destinataire comme destination du devis.

2. Créer le devis de paiement

Utilisez POST /v3/quotes avec ces en-têtes :

Request headers

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

Request body

{
  "customerId": "${CUSTOMER_ID}",
  "capabilityId": "${CAPABILITY_ID}",
  "in": {
    "amount": "150.00",
    "currency": "USDC",
    "accountId": "${SOURCE_WALLET_ID}"
  },
  "destinationId": "${PAYOUT_DESTINATION_ID}",
  "out": {
    "currency": "USD"
  }
}

Stockez data.id en tant que QUOTE_ID et présentez le prix et les frais renvoyés.

Choisir une route bancaire

Pour un paiement crypto vers fiat, vous pouvez définir le champ facultatif institutionId pour exiger une route bancaire approuvée pour le client. Omettez-le pour utiliser le routage automatique.

Request body with institutionId

{
  "customerId": "${CUSTOMER_ID}",
  "capabilityId": "${CAPABILITY_ID}",
  "institutionId": "${INSTITUTION_ID}",
  "in": {
    "amount": "150.00",
    "currency": "USDC",
    "accountId": "${SOURCE_WALLET_ID}"
  },
  "destinationId": "${PAYOUT_DESTINATION_ID}",
  "out": {
    "currency": "USD"
  }
}

Un institutionId explicite ne se rabat jamais sur une autre banque. Lorsque la banque sélectionnée n’a pas de route prête pour ce client, cette capacité et cette destination, POST /v3/quotes renvoie 422 bank_not_supported_for_customer avec le pointeur /institutionId.
institutionId n’est valide que sur les devis de paiement crypto vers fiat. L’envoyer sur un devis d’encaissement, de carte ou de transfert de stablecoin renvoie 400 validation_error.
Les lectures du devis et du transfert renvoient l’institutionId de la route sélectionnée, y compris lorsqu’elle a été sélectionnée automatiquement, lorsque la banque peut être identifiée.

Paiements SWIFT

En production, les paiements SWIFT en USD nécessitent une capacité SWIFT prête qui prend en charge les paiements (swift_pooled ou swift_named) et sont financés en USDC sur Ethereum, Base ou Polygon, ou en USDT sur Ethereum ou Polygon. Le montant reçu par le bénéficiaire après frais doit être d’au moins 100.00 USD. Une destination SWIFT nécessite l’adresse postale de la banque dans bankAddress, bankCity, bankState et bankPostalCode. Le pays du BIC doit correspondre au pays de la banque. Swipelux reprend l’adresse du bénéficiaire depuis le profil du client ou du destinataire.

Paiements Pix

Les destinations de destinataires Pix et Pix Safe reçoivent des BRL. Créez le devis de paiement avec la capacité Pix prête du client (pix_pooled), financez-le en USDC et définissez out.currency sur BRL. L’USDT ne peut pas financer un paiement en BRL. Un paiement Pix ne peut pas comporter de frais développeur. Si le compte source a des frais développeur, définissez fees.breakdown.developer sur {"fixed": "0.00", "bips": 0} dans la requête de devis. Sinon, POST /v3/quotes renvoie 400 validation_error. Swipelux ne calcule le prix du devis qu’une fois les coordonnées bancaires de la destination approuvées. Pendant leur vérification, POST /v3/quotes renvoie 400 validation_error avec un detail indiquant que la destination est encore en cours de vérification : demandez donc un nouveau devis une fois la vérification terminée. Si les coordonnées bancaires ont été rejetées ou si la configuration de la destination est incomplète, le detail vous invite plutôt à contacter le support, et les nouveaux devis continuent d’échouer jusqu’à ce que le support termine la configuration. Si la vérification ne peut pas être contrôlée, il renvoie 503 quote_temporarily_unavailable ; réessayez plus tard.

3. Exécuter le paiement

Créez le transfert avec POST /v3/transfers. Utilisez une nouvelle clé pour cette exécution prévue :

Request headers

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

Request body

{
  "quoteId": "${QUOTE_ID}"
}

Stockez le data.id du transfert en tant que TRANSFER_ID. Une création réussie lance le paiement ; elle ne prouve pas la livraison.

4. Suivre la livraison

Lisez GET /v3/transfers/{transferId} après la création et après chaque événement. Utilisez les derniers data.state, data.stateDetail et data.openTaskIds pour décider s’il faut attendre, agir ou afficher un résultat terminal. Ensuite, consultez Devis et transferts pour des montants exacts, une récupération d’exécution sûre et les tâches de transfert.

Commencer

Intégrer les clients

Construire les flux monétaires

Mise en production

Envoyer des fonds

Avant de commencer

1. Préparer la destination

2. Créer le devis de paiement

Choisir une route bancaire

Paiements SWIFT

Paiements Pix

3. Exécuter le paiement

4. Suivre la livraison

​Avant de commencer

​1. Préparer la destination

​2. Créer le devis de paiement

​Choisir une route bancaire

​Paiements SWIFT

​Paiements Pix

​3. Exécuter le paiement

​4. Suivre la livraison

Avant de commencer

1. Préparer la destination

2. Créer le devis de paiement

Choisir une route bancaire

Paiements SWIFT

Paiements Pix

3. Exécuter le paiement

4. Suivre la livraison