Developer documentation

Create payment or payment agreement URL

POST 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 a business_entity external 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_agreement field 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 MobilePay
    • quickpay-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.