Chained Payments & Rebilling (3 recipients)

Du er her:
Anslået læsetid: 5 min

Yourpay Chained Payment method is when there are three recipients of funds.

The functionality is commonly used by marketplaces who are carring a transaction for the author and the referee.

To secure both the Author and the marketplace, Yourpay’s unique Chained Payments is automatially splitting the payments into three chained-payments, one for each party in the chain.

The Master (Keyholder) is always able to capture and release the full payment, where the Slaves (Chained) automatially will follow the instructions of The Master.

This guide is split into three steps:

1. Chargeing the consumer & creating the payments for each recipient. (Create Payment with multiple recipients)

2. Captureing the each payment made in the previous step.(Capture Chained Payment though capture_payment)

3. Rebilling the consumer based on the ccrg id.

1. Create Payment with multiple recipients

To get started please see included code example here.

TIP You can open the file with notepad, if you do not have an editor for viewing source code.

There are different variables which needs to be defined in the setup. Look at the table below:

Variable Name Description
$MerchantNumber merchantid of the 1.recipient
$MerchantNumber2 merchantid of the 2.recipient
$MerchantNumber3 merchantid of the 3.recipient
$amount Total amount to be charged on the consumers credit card. OBS: 100 = 1 DKK, EUR
$Chainedamount The amount deducted from $amount to be sent to the 2. recipient
$ChainedamountThree The amount deducted from $amount to be sent to the 3. recipient.
$accepturl URL to redirect the consumer to after the payment has been processed.
$callbackurl The page where we should send IPN’s to. If you dont have a IPN listener page you can just give it an empty string or leave it as it is. You can read more about IPN here
$time $time should contain a unix timestamp of the moment of the transaction. If you’re using PHP you can use the function time()
$currencycode The ISO-4217 id of the currency you want to receive the payment in, e.g. 978 for Euro. For a complete list of codes look here.
$orderid Here we specify our orderid.
$ccrg If we want to save the consumers credit card details for later rebilling. If that is the case we put a ‘1’ there, otherwise we disable it with a ‘0’.
$language Language code that we want to use in the payment window. For a full list of language codes look here.
$comments Additional comments to the transaction.
$ct If the consumer should pay the transaction fee. If $ct is set to “on” the transaction fee will be forwarded to be consumer.

Now when you run the code we are presented with a link that sends the consumer to the payment window. To complete the transaction.

betalingsvindue.PNG

After the consumer have paid, he/she will then be redirected to the url specified in $accepturl,

and we will send back the following response:

process_payment_chained3_resp.PNG

Variable Name Description
uxtime Unix timestamp of the moment the callback was created.
MerchantNumber The merchantid for the 1. recipient
tid PaymentID for the payment belonging to the 1.recipient. You need this to capture the payment.
tchecksum SHA1 (PaymentID + integration code) Must match checksum.
checksum SHA1 (PaymentID + integration code) Must match tchecksum.
orderid Order id specified in process.
ShopPlatform The platform used to pay with yourpay.
amount The total amount to be charged on the consumers card. Remember 100 = 1
split Always 0.
date Date stamp of the transaction
cvc Always empty
expmonth Expiration month
expyear Expiration year
tcardno Hashed card number. The first six & the last four digits of the card are sent the rest is replaced with X
time Unix timestamp of the moment the payment was processed.
cardid The cardtype used e.g. VISA, MasterCard. ‘2’ & ‘3’ is for VISA & ‘4’ is for MasterCard
currency The ISO-4217 id of the currency the payment was made in.
amounted The amount available to capture for the 1. recipient. Remember 100 = 1
chainedMerchantNumber The merchantid of the 2. recipient
chainedtid The PaymentID of the payment belonging to the 2. recipient. You need this when you want to capture the payment.
chainedamount The amount available to capture for the 2. recipient. Remember 100 = 1
chainedMerchantNumberThree The merchantid of the 3. recipient
chainedtidthree The PaymentID of the payment belonging to the 3. recipient.
chainedamountthree The amount available for capture for the 3. recipient. Remember 100 = 1
ctfee The transaction fee.


If ccrg is turned on it will also be in the response. You need store that id from the response because you need it for rebilling, as it serves as our key to the customers saved credit card details.

Now there are one payment available to each merchant. Note if the 2. & 3. recipient are child domains owned by the 1.recipient(master), the master will be able to see payments belonging to 2. & 3. recipient, and 2. & 3 recipient will only be able to see their own payments.

2. Capture Chained Payment through capture_payment

If the 1.recipient (master) need to capture payments for himself and his sub-merchants, (2. & 3. recipient) he can make use of the following code example: here.

TIP You can open the file with notepad, if you do not have an editor for viewing source code.

If you run this code you are presented with a form that look like this:

capture_payment_chained_form.PNG

Each field except from the first, requires information from the response from when you first created the payments. Below is a table that explains what to input in the form.

Input Parameter Name Description
Activation of Chained Payments chainedpayment This should always be set to the value ‘1‘ to ensure activation of chained payments.
MerchantID 1: (Master) merchantid Here we specify the merchantid of the 1. recipient (master)
PaymentID identifier – Merchant 1 paymentid PaymentID of the payment belonging to 1. recipient. This value can be found under the key “tid” in the response body from when you created the payments.
Amount to capture from merchant 1 amount The amount to capture from 1. recipient. The amount available to capture can be found in “amounted”
PaymentID identifier – Merchant 2 chainedpaymentid PaymentID of the transaction belonging to the 2. recipient. This id can be found in the response body under the key “chainedtid”
Amount to capture from merchant 2 amountchained Amount to capture from 2. recipient. The amount available to capture for this recipient can be found in the response body under the key “chainedamount”.
PaymentID identifier – Merchant 3 chainedpaymentidThree PaymentID for the payment belonging to 3. recipient. This value can be found under the key “chainedtidthree” in the response.
Amount to capture from merchant 3 amountchainedThree Amount to capture for 3. recipient. The amount available for capture can be found in the response body under the key “chainedamountthree”.
TimeID identifier timeid TimeID of the transaction. This can be found under the key “time” in the response.

Now we are ready to submit the data to the API.

If everything is filled out correctly, you have successfully captured the three payments. Each merchants’ captured payment can now be found in “Captured Payments” in each merchant’s yourpay dashboard.

3. Rebilling the consumer

We made it really simple to rebill a consumers credit card. A code example can be found here.

TIP You can open the file with notepad, if you do not have an editor for viewing source code.

OBS: To use this functionality you need to provide the CCRG id mentioned in step 1.

To rebill we require three pieces of information:

– Who should receive the money?

– How much should each recipient receive?

– Which credit card should we capture from?

So in the code the following variables should be set:

Variable Name Description
$MerchantNumber merchantid of the 1.recipient
$MerchantNumber2 merchantid of the 2.recipient
$MerchantNumber3 merchantid of the 3.recipient
$subscriptioncode CCRG id from payment window or process_payment back in step 1.
$amount Total amount to be charged on the consumers card.
$amount2 Amount to deduct from $amount to be sent to recipient 2.
$amount3 Amount to deduct from $amount to be sent to recipient 3.


If everything is filled out and the ccrg you provided is valid, when you run the code it sends a request to our API function rebilling_customer, and you get a response similar to this:

rebilling3_chained.PNG

Now the customers credit card is successfully rebilled, and each merchant can find their payment in “captured payments” in their respective yourpay admin dashboard.