Billing Agreement - Luxon Pay

The Billing Agreement function streamlines the payment process, providing a faster checkout experience for users.

This feature streamlines transactions by enabling users to link their Luxon wallet to their account on your platform. After establishing this link, you can initiate transfers on the user’s behalf, eliminating the need for them to log in every time and significantly speeding up the transaction process.

Create a billing agreement within a payment method

In order to create a Billing agreement within a payment method, you have to add a 'createBillingagreement=true' parameter in the request body.

Upon setting the createBillingAgreement to true, users will be redirected to the login page.

The URL format will be:'/payment-details/{transactionId}?createBillingAgreement=true’.

Following the login, a pop-up will be displayed prompting the user to either confirm or decline the Billing Agreement. For visual reference, please see the attached image.

Should the user choose ‘Continue’, the Billing Agreement (BA) will be set for subsequent transactions and the payment will be a OneClick payment.

It’s important to note that, after creating the initial agreement with the ‘createBillingagreement=true’ parameter, Luxon will send you the ‘bilingAgreementID’ via a webhook.

You should store this ID for subsequent user deposits. For future transactions, you need to send Luxon the ‘bilingAgreementID’ without the ‘createBillingagreement’ parameter to prevent duplicate agreements for the same user.

Request Parameters

Name	Type	Description
merchantTransactionId	String	A Unique ID to identify the transaction.
merchantUserId	String	A unique ID to identify the user.
redirectUrl	String	The URL we redirect the customer to after the payment is completed.
comment	String	A text comment that accompanies the deposit (visible to the user and merchant).
amount	Integer	A positive integer in cents representing how much the user wishes to deposit. e.g. 100 EUR would be 10000 / 50 USD would be 5000
currency	String	The ISO 3 letter currency code in lowercase, see the supported currency list for details.
createBillingAgreement	boolean	Specifies the creation of an agreement between the user and merchant for OneClick payments.

Request format

{ "merchantTransactionId": "string", "merchantUserId": "string", "redirectUrl": "string", "comment": "string", "amount": number, "currency": "String", "createBillingAgreement": boolean }

Response Parameters

Name	Type	Description
transactionId	String	A unique Luxon transaction identifier that can be used as a reference in other API calls.
transactionUrl	String	The URL a user should be redirected to so they can authorize the payment.
status	String	A status object with the results of the call.

Response Format

{
"transactionId": "string",
"transactionUrl": "string",
"status": {
	"code": "string", "message": "string"
}
}

Request Body Example

{ "amount": 50000, "redirectUrl": "https", "useBrand": false, "merchantTransactionId": 648513721, "billingAgreementId": null, "comment": null, "currency": "USD", "merchantUserId": 876226, "recipientWallet": null, "createBillingAgreement": true, "brand": null }

Response example

{
"status": {
	"code": "PENDING",
	"message": "Transaction has been successfully initiated",
	"detail": null
},
"transactionId": "0be53a99-***-47fe-***-fa95a917706e",
"transactionUrl": "https://merchants.int.luxon.com/#/payment-details/0be53a99-****-47fe-****-fa95a917706e?createBillingAgreement=true"
}

Create a billing agreement without a payment transaction

This facilitates the establishment of a new Billing Agreement (BA) between you and the user without an immediate payment transaction.

ENDPOINT

POST.../api/v1/merchant/billing-agreements

Requests Parameters

Name	Type	Description
durationInDays	Integer	The number of days until the BA expires.
redirectUrl	String	The URL to which the user should be redirected after BA confirmation.

Request Body Example

{ "durationInDays": 30, "redirectUrl": "https://your-redirect-url.com/confirmation" }

Response Parameters

Name	Type	Description
agreementId	String	The unique ID assigned to the created BA.
startDay	Timestamp	The starting date of the billing agreement.
endDay	Timestamp	The end date of the billing agreement.
redirectUrl	String	The URL to which the user should be redirected for BA confirmation.

Response Body Example

{ "agreementId": "ba_123456789", "startDay": "2023-09-22T00:00:00Z", "endDay": "2023-10-22T00:00:00Z", "redirectUrl": "https://your-redirect-url.com/confirmation" }

Notes:

The redirectUrl provided in the request will be utilized to redirect the customer after the BA is confirmed.
The redirectUrl provided in the response will be used to redirect the customer for BA confirmation.
The agreementId serves as a unique identifier for the billing agreement and should be used for any future references to this agreement.
The startDay and endDay timestamps adhere to the ISO 8601 format.

A billing agreement will always be created for a specific merchant and a specific user account. There is no need to explicitly state the merchantID in the request, it is inferred from the HMAC header as for all the endpoints.

Get Billing Agreement

The Request body should be null.

The Response will contain startDate, endDate, and the status.

ENDPOINT

GET.../API/v1/merchant/billing-agreements/{id}

Cancel Billing Agreement

If a user decides to cancel a Billing Agreement, you must notify Luxon using this endpoint:

POST.../API/v1/merchant/billing-agreements/{id}/cancel

Upon receipt, Luxon will respond, indicating the current status of the Billing Agreement, which could be any of the following:

PENDING
CONFIRMED
CANCELED

If a Billing Agreement has been canceled and you wish to re-establish it, you can do so by sending a new request with the “createBillingAgreement” parameter set to true.

Make sure that if a Billing agreement has been canceled using the above endpoint, the merchant needs to delete the agreement ID related to the agreement that was canceled from their DB in order to not send an invalid agreement ID to Luxon.