menu

Payment API

What's on this page

Online Payments / Payouts / Split Payout

Split Payout

The funds we collect as a result of your payments are transferred to your bank account. You can also request that the payout should be split up and paid out to other merchants. This can be achieved by adding payout instructions to the payment request. Each payout instruction indicates the amount that should be paid out to a specific merchant.

Business Case

Imagine a platform where multiple merchants offer their products. Customers can buy products from these different merchants in the same sale. This results in one payment where the collected funds are distributed between all merchants participating in the sale.

Requirements

The merchants you want to refer to in payout instructions need to be boarded and linked to your merchant account. We provide you the external reference you need to use in the payout instruction to refer to each merchant for payout.

If you want to be able to refer to yourself in payout instructions, you also need an external reference to refer to yourself.

Payments

When payout instructions are added to the payment request, the PSP will split the payout between the given merchants after receiving the collected funds.

Refunds

Successful payments performed in a Split Payout matter can also be refunded using a refund request. In that case the refund must contain Payout Instructions as well. The reason is that you need to indicate which merchants will be accounted for the refund to the consumer.

Partial refunds

It is allowed to do a partial or full refund for the same payment, as long as the refund limit is not reached. The refund limit is applicable to the original payment amount and the individual payout instructions’ amounts. This means that the refund amount cannot exceed the refund limit of the original payment request and each payout instruction cannot exceed the refund limit of the original payment’s payout instructions.

Payout process

Every day a payout balance is calculated based on each individual merchant’s payout instructions. The amount of each payout instruction for payments will be added to the open payout balance of each individual merchant. The amount of each payout instruction for refunds will be subtracted from the balance. Since balances are calculated each day, it is possible that there is no payout to the individual merchant if the balance is equal to zero.

During the payout process, additional payout information will become available through the API.

Payout information

For Split Payout the payout information is not stored on the Payment Entity but on the Payout Instructions since they are paid out separately.

The following data is available per Payout Instruction for Payments as well as Payout Instruction for Refunds:

Name Description
paidout A boolean value that indicates that this payout instruction is settled with the merchant. Possible values: yes or no
paidoutDate An epoch timestamp for when the settlement was calculated.
unstructuredReference The message used in the payout to the sub merchant.
paidoutReference Unique reference to all payout instructions involved in the settlement for one particular merchant.

Info

paidout: “yes” does not necessarily mean that there was money transferred to the merchant’s bank account. It is possible that refunds neutralized the sales and a balance of EUR 0 was calculated.

Use Cases

Payment and Refund

This example is based on a standard card payment with payout instructions.

  1. You initiate a new payment with payout instructions

    {
    "amount": 23.45,
    "currency" : "eur",
    "method" : "card",
    "returnUrl" : "https://shop.merchant.com/return?order=123456",
    "merchantOrderReference" : "123456",
    "description" : "Order 123456",
    "language" : "nld",
    "billingAddress": "Westvoortsedijk",
    "billingCity": "Arnhem",
    "billingState": "GE",
    "billingPostalCode" :"6827 AT",
    "billingCountry": "NL",
    "billingHouseNumber": "55",
    "payoutInstructions" : [ 
      {
        "externalReference" : "lamp_shop",
        "amount" : 15.01
      }, {
        "externalReference" : "cable_shop",
        "amount" : 4.99
      }, {
        "externalReference" : "food_shop",
        "amount" : 3.45
      } 
    ]
}

  2. CCV Pay responds with a generated transaction containing a unique payUrl

     {
     "language": "nld",
     "method": "card",
     "currency": "eur",
     "billingAddress": "Westvoortsedijk",
     "billingPostalCode": "6827 AT",
     "billingCity": "Arnhem",
     "billingState": "GE",
     "billingCountry": "NL",
     "created": 1610111865939,
     "payoutInstructions": [
     {
         "externalReference": "lamp_shop",
         "amount": 15.01
     },
     {
         "externalReference": "cable_shop",
         "amount": 4.99
     },
     {
         "externalReference": "food_shop",
         "amount": 3.45
     }
     ],
     "merchantOrderReference": "123456",
     "lastUpdate": 1610111865939,
     "returnUrl": "https://shop.merchant.com/return?order=123456",
     "reference": "C210108141745898CB87E182.2",
     "billingHouseNumber": "55",
     "details": {
         "qrCode": "https://shop-vpos-test.ccvlab.eu/bep/authenticate.html?secureTransferId=2231cd51&trm=50",
         "urlIntent": "https://shop-vpos-test.ccvlab.eu/bep/authenticate.html?secureTransferId=2231cd51&trm=51"
     },
     "cancelUrl": "https://api-accept.psp.ccv.eu/card/cancel/merchant?reference=C210108141745898CB87E182.2",
     "amount": 23.45,
     "payUrl": "https://api-accept.psp.ccv.eu/card/payment.html?reference=C210108141745898CB87E182.2",
     "description": "Order 123456",
     "status": "pending",
     "type": "sale"
 }

  3. You redirect the customer to the payUrl

  4. The customer finalises the payment

  5. You need to check the status of the payment by Reading the Transaction.

    If the payments succeeds, the transaction is updated with status success

    {
     "language": "nld",
     "method": "card",
     "currency": "eur",
     "billingAddress": "Westvoortsedijk",
     "billingPostalCode": "6827 AT",
     "billingCity": "Arnhem",
     "billingState": "GE",
     "billingCountry": "NL",
     "brand": "visa",
     "created": 1610111865939,
     "methodTransactionId": "test-e1ebc659-1d60-492c-a8ca-93f79327e4fe",
     "payoutInstructions": [
         {
             "externalReference": "lamp_shop",
             "amount": 15.01,
             "paidout": "no"
         },
         {
             "externalReference": "cable_shop",
             "amount": 4.99,
             "paidout": "no"
         },
         {
             "externalReference": "food_shop",
             "amount": 3.45,
             "paidout": "yes"
         }
     ],
     "paidout": "no",
     "merchantOrderReference": "123456",
     "lastUpdate": 1610111919539,
     "returnUrl": "https://shop.merchant.com/return?order=123456",
     "reference": "C210108141745898CB87E182.2",
     "billingHouseNumber": "55",
     "entryMode": "ecom",
     "details": {
         "cardholderFirstName": "john",
         "qrCode": "https://shop-vpos-test.ccvlab.eu/bep/authenticate.html?secureTransferId=2231cd51&trm=50",
         "maskedPan": "4111XXXXXXXX1111",
         "urlIntent": "https://shop-vpos-test.ccvlab.eu/bep/authenticate.html?secureTransferId=2231cd51&trm=51",
         "cardholderLastName": "doe"
     },
     "cancelUrl": "https://api-accept.psp.ccv.eu/card/cancel/merchant?reference=C210108141745898CB87E182.2",
     "amount": 23.45,
     "payUrl": "https://api-accept.psp.ccv.eu/card/payment.html?reference=C210108141745898CB87E182.2",
     "description": "Order 123456",
     "status": "success",
     "type": "sale"
 }

  6. You Initiate a refund for the previous payment.

    In this example the total refund amount is EUR 14.99. Merchant lamp_shop will stand in for a partial refund of EUR 10.00 . Merchant cable_shop will be accounted for a full refund of EUR 4.99 .

    {
    "amount": 14.99,
    "reference": "C210108141745898CB87E182.2",
    "payoutInstructions" : [ {
            "externalReference" : "lamp_shop",
            "amount" : 10.00
        }, {
            "externalReference" : "cable_shop",
            "amount" : 4.99
        }
    ]
}

  7. CCV Pay responds with a generated refund

    {
    "language": "nld",
    "method": "card",
    "currency": "eur",
    "brand": "visa",
    "created": 1610112093036,
    "payoutInstructions" : [ 
      {
        "externalReference" : "lamp_shop",
        "amount" : 10.00
      }, {
        "externalReference" : "cable_shop",
        "amount" : 4.99
        }
    ],
    "merchantOrderReference": "123456",
    "lastUpdate": 1610112093036,
    "returnUrl": "https://shop.merchant.com/return?order=123456",
    "reference": "C210108142133020CB87E180.2",
    "amount": 14.99,
    "status": "success",
    "type": "refund"
}

  8. CCV Pay collects the funds for the payment and calculates the payout balances for each merchant.

    The calculated balance of Merchant lamp_shop will be EUR 5.01 (15.01 - 10.00 = EUR 5.01).

    Merchant cable_shop has a calculated balance of EUR 0 (4.99 - 4.99 = EUR 0) and will not be paid out.

    Merchant food_shop has a balance of EUR 3.45.

  9. You read the payout information for the Payment.

       {
      "language": "nld",
      "method": "card",
      "currency": "eur",
      "billingAddress": "Westvoortsedijk",
      "billingPostalCode": "6827 AT",
      "billingCity": "Arnhem",
      "billingState": "GE",
      "billingCountry": "NL",
      "brand": "visa",
      "created": 1610111865939,
      "methodTransactionId": "test-e1ebc659-1d60-492c-a8ca-93f79327e4fe",
      "payoutInstructions": [
        {
          "externalReference": "lamp_shop",
          "amount": 15.01,
          "paidout": "yes",
          "paidoutDate": 1605258439475,
          "unstructuredReference": "579fd569 AFREK. CCV PAY DAT. 20201113/0318 AANT. 2 MREF. Lamp Shop",
          "paidoutReference": "579fd569"
        },
        {
          "externalReference": "cable_shop",
          "amount": 4.99,
          "paidout": "yes",
          "paidoutDate": 1605258439493,
          "unstructuredReference": "72b8ddd4 AFREK. CCV PAY DAT. 20201113/0318 AANT. 2 MREF. Cable Shop",
          "paidoutReference": "72b8ddd4"
        },
        {
          "externalReference": "food_shop",
          "amount": 3.45,
          "paidout": "yes",
          "paidoutDate": 1605258439493,
          "unstructuredReference": "72b8ddd4 AFREK. CCV PAY DAT. 20201113/0318 AANT. 1 MREF. Food Shop",
          "paidoutReference": "72b8ddd4"
        }
      ],
      "paidout": "no",
      "merchantOrderReference": "123456",
      "lastUpdate": 1610111919539,
      "returnUrl": "https://shop.merchant.com/return?order=123456",
      "reference": "C210108141745898CB87E182.2",
      "billingHouseNumber": "55",
      "entryMode": "ecom",
      "details": {
        "cardholderFirstName": "john",
        "qrCode": "https://shop-vpos-test.ccvlab.eu/bep/authenticate.html?secureTransferId=2231cd51&trm=50",
        "maskedPan": "4111XXXXXXXX1111",
        "urlIntent": "https://shop-vpos-test.ccvlab.eu/bep/authenticate.html?secureTransferId=2231cd51&trm=51",
        "cardholderLastName": "doe"
      },
      "cancelUrl": "https://api-accept.psp.ccv.eu/card/cancel/merchant?reference=C210108141745898CB87E182.2",
      "amount": 23.45,
      "payUrl": "https://api-accept.psp.ccv.eu/card/payment.html?reference=C210108141745898CB87E182.2",
      "description": "Order 123456",
      "status": "success",
      "type": "sale"
    }

    Payout Information for lamp_shop explained:

    Name Value Clarification
    paidout yes The payout instruction for this payment is settled.
    paidoutDate 1605258439475 Epoch value for November 13th, 2020 9:07:19
    unstructuredReference 579fd569 AFREK. CCV PAY DAT. 20201113/0318 AANT. 2 MREF. Lamp Shop 579fd569 is the paidoutReferenceId
    20201113 is the date when the transfer was submitted.
    AANT. 2 indicates there are 2 payout instructions involved in this settlement. One for the payment and one for the refund.
    paidoutReference 579fd569 Unique payout reference that groups all payout instructions enclosed in the merchant payout.

  10. You read the payout information for the Refund

        {
        "language": "nld",
        "method": "card",
        "currency": "eur",
        "brand": "visa",
        "created": 1610112093036,
        "payoutInstructions" : [ 
          {
            "externalReference" : "lamp_shop",
            "amount" : 10.00,
            "paidout": "yes",
            "paidoutDate": 1605258439383,
            "unstructuredReference": "579fd569 AFREK. CCV PAY DAT. 20201113/0318 AANT. 2 MREF. Lamp Shop",
            "paidoutReference": "579fd569"
          }, {
            "externalReference" : "cable_shop",
            "amount" : 4.99,
            "paidout": "yes",
            "paidoutDate": 1605258439493,
            "unstructuredReference": "72b8ddd4 AFREK. CCV PAY DAT. 20201113/0318 AANT. 2 MREF. Cable Shop",
            "paidoutReference": "72b8ddd4"
            }
        ],
        "merchantOrderReference": "123456",
        "lastUpdate": 1610112093036,
        "returnUrl": "https://shop.merchant.com/return?order=123456",
        "reference": "C210108142133020CB87E180.2",
        "amount": 14.99,
        "status": "success",
        "type": "refund"
    }

    Payout Information for cable_shop explained:

    Name Value Clarification
    paidout yes The payout instruction for this refund is settled. In this case there was no payout to the merchant since the refund neutralized the payment.
    paidoutDate 1605258439493 Epoch value for November 13th, 2020 9:07:19
    unstructuredReference 72b8ddd4 AFREK. CCV PAY DAT. 20201113/0318 AANT. 2 MREF. Cable Shop This unstructured message is generated by default. Since there was no payout, it can be ignored.
    paidoutReference 72b8ddd4 Unique payout reference that groups all payout instructions enclosed in the merchant payout.