# 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](/api/docs/server/retrievingcustomers.md#available-fields).
- `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:

```http
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:

```http
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:

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

```json
{
  "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:

```json
{
  "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.