Search

Are you looking for test card numbers?

Would you like to contact support?

Marketpay icon

Payouts to cards

Learn how to save your sub-merchant'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 cards. This feature is available in MarketPay 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

  1. Submit a POST /payments request with your sub-merchant's card details and the following parameters:

    You can only pass raw card data if you are PCI Level 1 or 2 certified. Otherwise, you should use our Custom Card Component to securely collect and encrypt your sub-merchant's card details.

    {
    "paymentMethod": {
       "type": "scheme",
       "number": "4111111111111111",
       "expiryMonth": "8",
       "expiryYear": "2020",
       "cvc": "737",
       "holderName": "John Smith"
    },
    "amount": {
       "value": 0,
       "currency": "USD"
    },
    "shopperReference": "YOUR_UNIQUE_SUBMERCHANT_ID_IOfW3k9G2PvXFu2j",
    "enablePayout": true,
    "reference": "YOUR_TRANSACTION_REFERENCE",
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
    }
    {
    "additionalData": {
        "recurring.recurringDetailReference": "8315659584588245",
        "recurring.shopperReference": "YOUR_UNIQUE_SUBMERCHANT_ID_IOfW3k9G2PvXFu2j",
        "merchantReference": "YOUR_TRANSACTION_REFERENCE",
        "fundsAvailability": "I",
        "payoutEligible": "Y"
    },
    "pspReference": "881566214605773J",
    "resultCode": "Authorised"
    }

    If you are using the Classic integration, set the recurring.contract parameter to PAYOUT and include this in your request.

  2. Check the payoutEligible parameter in the response. The value should either be:

    • 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 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

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

    {
    "accountHolderCode" : "4a55294d-7841-484d",
    "accountHolderDetails" : {
      "payoutMethods" : [
         {
            "merchantAccount" : "YOUR_MERCHANT_ACCOUNT",
            "recurringDetailReference" : "8315659584588245",
            "shopperReference" : "YOUR_UNIQUE_SELLER_ID_IOfW3k9G2PvXFu2j"
         }
      ],
      ...
    }
    }
    {
    "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 for 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"
    }
    {
    "invalidFields" : [],
    "merchantReference": "YOUR_PAYOUT_REFERENCE",
    "pspReference" : "9915402175055353",
    "resultCode": "Received"
  2. Wait for the ACCOUNT_HOLDER_PAYOUT notification to know if the payout has been successful.