# 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 boolean
  Whether to use UI designed to be run in an iframe, e.g. iframe=1.
• test boolean
  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. 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=quickpay-recurring-card.

  Allowed values

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

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

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

Unlike the update operations, which return user input errors with HTTP 422, these errors return with an HTTP 200 status code. An invoice_number that does not exist returns a plain text HTTP 404 error instead.

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.

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.