Aside from paying out to bank accounts, you also have the option to send payouts to eligible Mastercard and Visa cards. This feature is available in Fund API version 5 and later.
Contact our Support Team to enable card payouts for your marketplace.
Step 1: Check if the card is eligible for payouts and save the card details
-
Submit a POST /payments request with your sub-merchant's card details and the following parameters:
-
merchantAccount
: Your merchant account. -
shopperReference
: Your unique sub-merchant reference (minimum length three characters). -
enablePayOut
: Indicates if the card details should be stored for payouts. Set this to true. -
paymentMethod
: Object containing your sub-merchant's card details.
You can only pass raw card data if you are fully PCI compliant. Otherwise, use our Card Component to securely collect and encrypt your sub-merchant's card details.
{ "{hint:Your sub-merchant's card details}paymentMethod{/hint}": { "type": "scheme", "number": "4111111111111111", "expiryMonth": "3", "expiryYear": "2030", "cvc": "737", "holderName": "John Smith" }, "amount": { "value": 0, "currency": "EUR" }, "{hint:Your unique reference for this sub-merchant, minimum length 3}shopperReference{/hint}": "YOUR_UNIQUE_SUBMERCHANT_ID_IOfW3k9G2PvXFu2j", "enablePayOut": true, "reference": "YOUR_TRANSACTION_REFERENCE", "{hint:Your merchant account}merchantAccount{/hint}": "YOUR_MERCHANT_ACCOUNT" }
{ "additionalData": { "{hint: Use this when creating a payout method in step 2}recurring.recurringDetailReference{/hint}": "8315659584588245", "recurring.shopperReference": "YOUR_UNIQUE_SUBMERCHANT_ID_IOfW3k9G2PvXFu2j", "merchantReference": "YOUR_TRANSACTION_REFERENCE", "{hint: If value is I, this means that the card is eligible for instant payouts}fundsAvailability{/hint}": "I", "{hint: Indicates if this card is eligible for payouts}payoutEligible{/hint}": "Y" }, "pspReference": "881566214605773J", "resultCode": "Authorised" }
If you are using the Classic integration, include the
recurring.contract
: PAYOUT in your request. -
-
Check the
payoutEligible
parameter in the response. The value should be either:- Y: Eligible for payout. For Mastercard, this means that the card is eligible for both domestic and cross-border payouts.
- D: Applies only to Mastercard. Card is eligible only for domestic payouts.
If you receive an N or U, the card cannot be used for payouts.
- If the card is eligible for payouts, get the
recurring.recurringDetailReference
from the response. This is your sub-merchant's tokenized card details. You will need this value when adding the new payout method and for submitting future payout requests.
Step 2: Add card as a payout method
-
Submit a POST
/updateAccountHolder
request with the following parameters:-
shopperReference
: Your unique sub-merchant reference (minimum length three characters). -
recurringDetailReference
: This is therecurring.recurringDetailReference
returned in the response in Step 1.
{ "invalidFields" : [], "pspReference" : "9915402175055353", "accountHolderCode" : "4a55294d-7841-484d", "accountHolderDetails" : { ... "payoutMethods" : [ { "merchantAccount" : "YOUR_MERCHANT_ACCOUNT", "payoutMethodCode": "4a55294d-7841-484d-be06-2e6e9cac824f", "recurringDetailReference" : "9915402174902084", "shopperReference" : "YOUR_UNIQUE_SELLER_ID_IOfW3k9G2PvXFu2j" } ], ... } }
-
You receive a response that might contain any of the following status codes:
- HTTP 200: You can use the information returned in API response, such as the
payoutMethodCode
, but wait for the ACCOUNT_HOLDER_UPDATED notification before performing any business logic. The notification confirms when the new payout method has been added in our central database. - HTTP 202: The request has been acknowledged and added to the queue. Use the response to check and confirm the changes you made. Wait for the ACCOUNT_HOLDER_UPDATED notification to confirm if the new payout method has been successfully added. Get the corresponding
payoutMethodCode
from the notification.
Step 3: Submit a card payout
-
Submit a POST
/payoutAccountHolder
using thepayoutMethodCode
returned in the response or notification in Step 2.{ "accountCode" : "9915402177165382", "accountHolderCode" : "4a55294d-7841-484d", "amount" : { "currency" : "USD", "value" : 1000 }, "description" : "YOUR_DESCRIPTION", "merchantReference" : "YOUR_PAYOUT_REFERENCE", "payoutMethodCode" : "4a55294d-7841-484d-be06-2e6e9cac824f" }
- Wait for the ACCOUNT_HOLDER_PAYOUT notification to confirm the status of the payout.
Payout notifications
The ACCOUNT_HOLDER_PAYOUT may contain any of the following status.statusCode
:
statusCode |
Description | Action to take |
---|---|---|
Initiated | The payout has been scheduled to be sent to the sub-merchant's bank. | If the card supports instant payouts (fundsAvailability : I), the sub-merchant receives the funds immediately. Otherwise, inform your sub-merchant to expect the funds within a couple of business days. |
Failed | A payout can fail due to any of the following reasons:
pspReference , different from the initial payout. |
Check the notification and review why the payout failed.
|