API documentation

# Create payment or payment agreement URL

The create payment URL endpoint /api/createpaymenturl/ allows you pay for an invoice, create a new payment agreement or replace an existing agreement using the resulting payment gateway.

You can use any payment gateway integration that you have setup within Iteras. The resulting URL you will have to redirect to yourself. Also both a return URL and a cancel URL must be given, as these will be part of the resulting URL.

# Parameters

The endpoint uses POST.

The following two GET paramaters are mandatory:

  • "return_url" - where to redirect the customer after successful payment agreement creation, e.g. return_url=https://example.com/ordering/done/

  • "cancel_url" - where to redirect the customer in case the payment agreement process is cancelled, e.g. cancel_url=https://example.com/ordering/failed/

You also have the option of the following extra GET parameters:

  • "iframe" - whether to use UI designed to be run in an iframe, e.g. iframe=1

  • "test" - whether to accept transactions from test cards, e.g. test=1

The POST parameters depends of what is to be paid. The choices are either:

  • Pay an invoice: invoice_number (and possibly a business_entity external ID if you have overlapping invoice number series)
  • Replace a payment agreement (and pay anything not paid with the old agreement): payment_agreement_id. You can find the existing payment agreement ID for a customer using the subscriptions.payment_agreement.
  • Pay what needs to be paid for a subscription: subscription_id, which is the ID found when listing the subscriptions of the customer.
  • Pay what needs to be paid for a specific customer: both a customer_number and a business_entity external ID must be given in this case.

And then a required parameter "payment_method", e.g. payment_method=quickpay-recurring-card. It can be one of the following:

  • "adyen-recurring-card" for recurring payment with card if you have an integration with Adyen
  • "adyen-onetime-card" for payment with card if you have an integration with Adyen
  • "quickpay-recurring-card" for recurring payment with card if you have an integration with Quickpay
  • "quickpay-onetime-card" for payment with card if you have an integration with Quickpay
  • "epay-recurring-card" for recurring payment with card if you have an integration with ePay
  • "epay-onetime-card" for payment with card if you have an integration with ePay
  • "vippsmobilepay-recurring" - for paying with Vipps/MobilePay

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/ HTTP/1.1

invoice_number=528542
payment_method=quickpay-onetime-card

You can instead pay for all a customers subscriptions using a customer_number 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/ HTTP/1.1

customer_number=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/ HTTP/1.1

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..."
}

In case of a validation error, an error object with fields and arrays of error messages is returned:

{
  "errors": {
    "payment_method": "No payment integration found",
   }
}

You then redirect the customer to https://payments.examplegateway.com/?key=dx123js32..., and they either enter their details at the payment gateway, in which case the payment is confirmed, or quit, in which case the payment does not progress any further.

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 succesfully fiddling with it.

← Invoicing integration Javascript API: Overview →