Scroll to top

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": "****-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.



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

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


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



Cancel Billing Agreement

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


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


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.