Create payment or payment agreement URL
https://app.iteras.dk/api/createpaymenturl/
The API key must allow "Create payment URL".
Creates a URL where a customer pays an invoice, creates a new payment agreement or replaces an existing one through a payment gateway.
You can use any payment integration configured in Iteras. You just need to redirect the customer to URL returned.
Parameters
The parameters return_url, cancel_url, iframe and test go in the URL, the others in the request body. Give one of invoice_number, payment_agreement_id, subscription_id and customer to say what is to be paid.
-
return_url string
Where to redirect the customer after successful payment agreement creation, e.g.
return_url=https://example.com/ordering/done/. The default is the self-service overview of the business entity the payment is for. -
cancel_url string
Where to redirect the customer in case the payment agreement process is cancelled, e.g.
cancel_url=https://example.com/ordering/failed/. The default is the self-service overview of the business entity the payment is for. -
iframe bool
Whether to use UI designed to be run in an iframe, e.g.
iframe=1. -
test bool
Whether to accept transactions from test cards, e.g.
test=1. This does not work with all payment integrations. -
invoice_number string
Pay an invoice, e.g.
invoice_number=528542. If you have multiple business entities with overlapping invoice number series, you need to give abusiness_entityexternal ID too. -
payment_agreement_id string
Replace a payment agreement and pay what was not paid with the old agreement.
You can find the existing payment agreement ID for a customer by requesting the
subscriptions.payment_agreementfield from the customer data endpoint. -
subscription_id string
Set up a payment agreement for a subscription.
-
customer string
Pay what needs to be paid for a specific customer, by customer ID.
-
business_entity string
External ID of the business entity to pay within. Optional when another parameter identifies a single business entity or the account has only one.
-
payment_method string required
The payment method, one of those the payment integrations of the account support.
E.g.
payment_method=adyen-recurring-card. One of the methods the payment integrations support:adyen-recurring-card- Payment card - automatic payment (Adyen)adyen-onetime-card- Payment card - onetime payment (Adyen)adyen-recurring-sepadirectdebit- SEPA Direct Debit - automatic (Adyen)adyen-onetime-sepadirectdebit- SEPA Direct Debit - onetime (Adyen)vippsmobilepay-recurring- Vipps MobilePayquickpay-recurring-card- Payment card - automatic payment (Quickpay)quickpay-onetime-card- Payment card - onetime payment (Quickpay)epay-recurring-card- Payment card - automatic payment (ePay)epay-onetime-card- Payment card - onetime payment (ePay)epay-recurring-applepay- Apple Pay - automatic payment (ePay)epay-onetime-applepay- Apple Pay - onetime payment (ePay)paytrail-onetime-bank- Online banking - onetime payment (Paytrail)
Which of them you can use depends on the payment integrations set up for your account.
To get a URL for paying an invoice you might send the following request:
POST /api/createpaymenturl/?iframe=1&return_url=https://example.com/payment/done/&cancel_url=https://example.com/payment/cancelled/
invoice_number=528542
payment_method=quickpay-onetime-card
You can instead pay for all a customers subscriptions using a customer and a business_entity external ID:
POST /api/createpaymenturl/?iframe=1&return_url=https://example.com/payment/done/&cancel_url=https://example.com/payment/cancelled/
customer=123321
business_entity=DK-branch
payment_method=quickpay-onetime-card
To replace a payment agreement for a customer you will just need the payment_agreement_id of the old agreement:
POST /api/createpaymenturl/?iframe=1&return_url=https://example.com/payment/done/&cancel_url=https://example.com/payment/cancelled/
payment_agreement_id=623418
payment_method=quickpay-recurring-card
Return value
The data returned is an object like { "redirect_to":"https://payments.examplegateway.com/?key=dx123js32..." }.
{
"allowed_in_iframe": true,
"redirect_to":"https://payments.examplegateway.com/?key=dx123js32..."
}
When you get back the redirect_to, e.g. https://payments.examplegateway.com/?key=dx123js32...,
you redirect the customer to the URL. They either enter their details at the payment gateway, in which
case the payment is confirmed and they get redirected to the return_url you
specified, or quit, in which case the payment does not progress any further.
Errors
In case of a validation error, the response has created set to false
and an error message for each field that failed:
{
"created": false,
"errors": {
"payment_method": "No payment integration found"
}
}
Unlike the update operations, which return user input errors with HTTP 422, these
errors return with an HTTP 200 status code. A business_entity,
invoice_number, subscription_id, payment_agreement_id
or customer that does not exist returns a plain HTTP 404 error instead, without
a JSON body, and so does a business_entity that more than one business entity
has as external ID.
If the payment gateway fails, the response instead has an __all__ field
with a message meant for the customer.
If you need to save information about the customer across the
calls, you can use a cookie or put GET parameters in the continue
and cancel URLs, e.g. return_url=https://example.com/ordering/done/?sessionid=XYZ.
If it's important data, just remember to make it tamper-proof,
either by signing it (e.g. using something like Paseto) or
pointing to things you store in your database, to prevent
someone from fiddling with it.