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, 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": "8",
        "expiryYear": "2020",
        "cvc": "737",
        "holderName": "John Smith"
      },
      "amount": {
        "value": 0,
        "currency": "USD"
      },
      "{hint:Your unique reference for this sub-merchant}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.

  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 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",
              "{hint:Use this when submitting a payout in step 3}payoutMethodCode{/hint}" : "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.

    {
      "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 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:

  • Validation error. For example, payouts are not enabled for the account holder. You receive an invalidFields array in the notification.
  • Funds have been returned to Adyen. The notification is sent with status.message.code 10_069.

For detailed information on error codes and messages, refer to General error codes.

A failed payout will have a new pspReference, different from the initial payout.
Check the notification and review why the payout failed.

  • If you received invalidFields, the payout failed due to validation error. Review and update the account holder payout state, if needed.
  • If you received status.message.code 10_069, the payout failed because the funds have been returned to Adyen. Ask your sub-merchant to check and update their card payout details.

You can link the returned payout to the initial payout using the MarketPay payments accounting report.