Create Payment Link

Create new Payment Link.

To avoid duplicate payments, you must provide a unique_reference_id which uniquely identifies the bill/invoice being paid. This allows you to safely create/retry Payment Links multiple times using the same unique_reference_id, for example if a user restarts the payment flow on a different device. Finverse will only allow a single payment per unique_reference_id. See “Implementation guidance” section below for additional details on how to generate a unique_reference_id.

Authorization: customer_token

integration_metadata (object, optional)

Use the following optional parameters to pass custom values for Finverse-supported integrations (e.g. ERP/CRM/accounting integrations).

link_customizations (object, optional)

You can use the following optional parameters to customize the behaviour of Finverse Link’s UI to fit your implementation requirements.

payment_details (object, conditionally required)

Details describing the Payment transaction.

Required if mode = PAYMENT.

payment_setup_options (object, conditionally required)

Additional parameters to configure payment methods and future payments.

Required if mode = SETUP.

Impact of future_payments on payment methods displayed

When enabling future_payments:

• In mode = SETUP: the Finverse Link UI will only display payment methods which support recurring “pull” payments (e.g direct debit & cards).

• In mode = PAYMENT, the Finverse Link UI will continue to show all available payment methods, including one-time payment methods (in order to encourage payment completion).

  • The future payments setting will only apply if the user selects a payment method which supports recurring payments (e.g. direct debit or cards).

  • To enable future payments and display only recurring payment methods, use the (optional) payment_method_types filter to explicitly limit the payment methods displayed.

autopay_enrollment_configurations (object, optional)

Configures the FInverse Link UI to enroll users into autopay (i.e. collects consent for future payments).

This controls whether the Finverse UI will prompt users to opt-in to autopay, when autopay is not already enforced (i.e. when future_payments ≠ AUTOPAY).

When a user consents to autopay, the payment user property autopay_consent is set to true, which allows:

• User can be charged for payments (using POST /payments) without obtaining additional user consent for each charge;

• Finverse can automatically initiate charges on bill/invoice due dates (for customer apps where Finverse ingests bill/invoices via ERP integrations or API).

Note: autopay_enrollment_configurations cannot be set when future_payments = AUTOPAY (since this already enforces autopay for all users; no autopay enrollment screen is shown).

mandate_details (object, optional)

Optional configurations for any direct debit mandate setup by the user.

receipient_account_filters (object, optional)

Optional filter to narrow the list of accounts receiving money (also called “settlement accounts”). This is typically used for more complex payment scenarios, for example when a Customer App needs multiple settlement accounts:

• For different business units, or

• With different collection fee rules (e.g. with or without transaction fee surcharges paid by senders)

In these cases the Customer App can use recipient_account_filters to explicitly filter the receiving accounts matching its business requirements.

Note: settlement accounts are configured by Finverse during initial onboarding of each Customer App. By default, Finverse creates 1 recipient account per payment method. Contact [email protected] if you have complex payment flows, use cases or business units which may benefit from setting up multiple settlement accounts.

sender (object, required)

Details on the sender of the payment.

View More

Response fields

The response is a Payment Link object.

Refer to Payment Link object data model in GET /payments_links/{payment_link_id}.

Implementation guidance

Handling retries/revisit and avoiding duplicate payments: using unique_reference_id as idempotency key

• To enable retries/revisit, Finverse allows creating payment links using a previously-used unique_reference_id, if all payment link details are identical (amount, etc). This returns the same payment link ID and URL as originally created. This allows using unique_reference_id similarly to an idempotency key.

• To avoid duplicate payments, Finverse will only allow 1 executed payment per unique_reference_id.

• When a user revisits a payment link, the Finverse Link UI will show end-users a “Payment in progress” screen if a payment is already pending for the same unique_reference_id.

  • Example: if a user revisits a payment link after previously using the payment link to setup a direct debit mandate => the user will see “Payment in progress” if the direct debit mandate is still being processed; a payment will automatically be executed when the direct debit mandate becomes successful.

• unique_reference_id generation: we recommend generating unique_reference_id based on a composite/hash of the key payment details. The composite/hash should include any payment link details that could change between 2 user sessions, for example:

  • Bill/invoice/purchase reference (external_transaction_reference)

  • Payment amount

  • Sender details (sender.name, sender.email)

  • Metadata (metadata, payment_metadata).

  • This ensures that a new unique_reference_id is generated if any payment link details are modified (for example if the amount is updated or if the user changes their name/email between 2 user sessions).

• If a payment link creation request is sent using an existing unique_reference_id but different payment link details, the following API error will be returned:

// HTTP 400 Bad Request
{
    "error": {
        "details": "Trying to update existing paymentLink. Not supported.",
        "error_code": "INVALID_PARAMETER",
        "message": "The parameters provided are invalid. See details.",
        "request_id": "1689652320",
        "type": "API_ERROR"
    }
}