# Create payment or payment agreement URL

The create payment URL endpoint /api/createpaymenturl/ allows your customer pay for an invoice, create a new payment agreement or replace an existing agreement 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 following GET parameters go in the URL:

• return_url string required
  Where to redirect the customer after successful payment agreement creation, e.g. return_url=https://example.com/ordering/done/.
• cancel_url string required
  Where to redirect the customer in case the payment agreement process is cancelled, e.g. cancel_url=https://example.com/ordering/failed/.
• 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 doesn't work with all payment integrations.

The following POST parameters go in the request body. Give one of the first four to say what is to be paid:

• invoice_number string
  Pay an invoice, e.g. invoice_number=528542. The payment is applied to the invoice. If you have multiple business entities with overlapping invoice number series so the invoice number is not unique, you need to give a business_entity external ID too.
• payment_agreement_id string
  Replace a payment agreement and pay what wasn't 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
  Pay what needs to be paid for a subscription.
• customer string
  Pay what needs to be paid for a specific customer. Must be combined with a business_entity external ID.
• business_entity string
  External ID of the business entity to pay within. Optional when another parameter identifies a single business entity, and required together with customer.
• payment_method string required

  The payment method, 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.

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.