Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

Atenção, esta página não se encontra disponível em Português
Marketpay icon

Pay out to cards

Save your account holder's card details and make a payout to their card.

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

Step 1: Check card eligibility and save the card details

Before you can make a payout to a card, first you need to check if a card is eligible for payouts.

  1. Make a POST /payments request with the following parameters:

    Parameters Description
    enablePayOut Set this to true. This indicates if the card details should be stored for payouts.
    merchantAccount Your merchant account.
    paymentMethod Object containing the account holder's card details.
    shopperReference Your unique reference for the account holder (minimum length three characters).
    shopperName Object containing the account holder's name.
    billingAddress Object containing the account holder's billing address.

    The example below shows raw card data, which you can send only if you are fully PCI compliant. Alternatively, use our Drop-in or Card Component to securely collect and encrypt your account holder's card details.

    Submit a zero-value payment request
    curl https://checkout-test.adyen.com/v67/payments \
    -H "x-API-key: YOUR_X-API-KEY" \
    -H "content-type: application/json" \
    -d '{
         "{hint:Card details of account holder}paymentMethod{/hint}": {
           "type": "scheme",
           "number": "4111111111111111",
           "expiryMonth": "03",
           "expiryYear": "2030",
           "cvc": "737",
           "holderName": "John Smith"
         },
         "amount": {
           "value": 0,
           "currency": "EUR"
         },
          "billingAddress": {
             "houseNumberOrName":"17",
             "street":"Teststreet 1",
             "city":"San Francisco",
             "stateOrProvince":"CA",
             "country" : "US",
             "postalCode":"12345"
          },
         "shopperName" : {
            "firstName" : "John",
            "lastName" : "Smith"
         },
         "{hint:Your unique reference for this account holder, minimum char 3}shopperReference{/hint}": "UNIQUE_SELLER_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": "UNIQUE_SELLER_ID_IOfW3k9G2PvXFu2j",
        "merchantReference": "YOUR_TRANSACTION_REFERENCE",
        "{hint: If value is I, 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 Classic integration (/authorise), set recurring.contract to 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 the 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 the card as a payout method

Update the account holder to include the card as a payment method.

  1. Make a POST /updateAccountHolder request with a payoutMethods array containing the following:

    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: Pay out to the card

Make a POST /payoutAccountHolder request using the payoutMethodCode returned in the response or notification in Step 2.

Submit a payout to the card
curl https://cal-test.adyen.com/cal/services/Fund/v6/payoutAccountHolder \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
  "accountCode" : "9915402177165382",
  "accountHolderCode" : "4a55294d-7841-484d",
  "amount" : {
    "currency" : "USD",
    "value" : 1000
  },
  "description" : "YOUR_DESCRIPTION",
  "merchantReference" : "YOUR_PAYOUT_REFERENCE",
  "payoutMethodCode" : "4a55294d-7841-484d-be06-2e6e9cac824f"
}'

Payout requests are processed asynchronously so in the response, we only inform you that we received your request. You'll need to rely on the ACCOUNT_HOLDER_PAYOUT notification to know the status of the payout.

Response
{
  "invalidFields" : [],
  "merchantReference": "YOUR_PAYOUT_REFERENCE",
  "pspReference" : "9915402175055353",
  "resultCode": "Received"
}

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 account holder's card. If the card supports instant payouts
(fundsAvailability:I), the account holder receives the funds immediately. Otherwise, inform your account holder 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 the account holder to check and update their card payout details.

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

See also