Search

Are you looking for test card numbers?

Would you like to contact support?

Marketpay icon

Payouts to cards

Learn how to save your account holder's card details and make a payout.

Aside from paying out to bank accounts, you also have the option to send payouts to eligible Mastercard and Visa debit cards. This feature is available in Fund API version 5 and later.

When paying out to cards, the funds arrive to the cardholder within 30 minutes and there is no dependency on bank cutoffs.

Before you begin

Contact our Support Team to enable card payouts for your platform.

Step 1: Check if the card is eligible for payouts and save the card details

  1. Submit a POST /payments request with your account holder's card details and the following parameters:

    • merchantAccount: Your merchant account.
    • shopperReference: Your unique account holder reference (minimum length three characters).
    • enablePayOut: Indicates if the card details should be stored for payouts. Set this to true.
    • paymentMethod: Object containing your account holder'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 account holder's card details.

    Submit a zero-value payment request
    {
      "{hint:Your account holder'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 account holder, 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"
    }
    Response
    {
      "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 recurring.contract PAYOUT in your request.

  2. 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.

  3. If the card is eligible for payouts, get the recurring.recurringDetailReference from the response. This is your account holder'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

  1. Submit a POST /updateAccountHolder request with the following parameters:

    Update account holder request
    Response
    {
      "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

  1. Submit a POST /payoutAccountHolder using the payoutMethodCode returned in the response or notification in Step 2.

    Submit a payout to the card
    {
      "accountCode" : "9915402177165382",
      "accountHolderCode" : "4a55294d-7841-484d",
      "amount" : {
        "currency" : "USD",
        "value" : 1000
      },
      "description" : "YOUR_DESCRIPTION",
      "merchantReference" : "YOUR_PAYOUT_REFERENCE",
      "payoutMethodCode" : "4a55294d-7841-484d-be06-2e6e9cac824f"
    }
    Response
    {
      "invalidFields" : [],
      "merchantReference": "YOUR_PAYOUT_REFERENCE",
      "pspReference" : "9915402175055353",
      "resultCode": "Received"
    }
  2. Wait for the ACCOUNT_HOLDER_PAYOUT notification to confirm the status of the payout.
    For more information, see Payout notifications.

See also