Skip to main content
The Adyen payment integration is currently in beta. Reach out to the Orb team to have it enabled for your account.
Orb supports Adyen as a payment gateway. Once Adyen is connected and a customer is mapped to it, Orb can collect payment on invoices through the Orb invoice portal and via auto-collection, using the payment methods enabled on your Adyen merchant account.

​
Setup

​
Connecting Adyen with Orb

Adyen connects with API credentials that you generate in your Adyen Customer Area.
  1. In the Orb dashboard, navigate to Settings > Integrations and select Connect to Adyen.
  2. Provide:
    • API key: an Adyen API key with the Management API “Webhooks read and write” and “API credentials read and write” roles. Orb uses these roles to provision the webhook and client key on your behalf.
    • Merchant account: the merchant account code you want Orb to transact against.
    • Live URL prefix: required when connecting in live mode (and only then). This is the prefix Adyen assigns to your live API endpoints.
  3. Orb validates the credentials, then automatically:
    • registers a webhook from your Adyen account back to Orb (including the HMAC key used to verify it),
    • allowlists the Orb invoice portal as an origin, and
    • configures the client key the portal uses to render the payment form.
    You do not need to configure a webhook or client key manually in Adyen.
In test mode, Orb connects to your Adyen test environment, so you can exercise the full payment flow safely with Adyen test cards. Live mode connects to your live environment and requires the live URL prefix.
Orb treats a successful authorization as payment received, so your Adyen merchant account should be configured for automatic capture. If your account uses manual or delayed capture, contact the Orb team before going live.

​
Configuring customers

When creating or updating customers in the Orb UI, select Adyen as the Payment Provider. Customer mappings can also be configured in the API by setting payment_provider to adyen. You do not need to supply a payment_provider_id. Adyen uses a shopperReference to anchor a customer’s stored payment methods, but Orb manages this for you (using the Orb customer ID), so mapping a customer to adyen is sufficient for Orb to collect payment once the account is connected.

​
Paying invoices

When a customer opens an invoice in the Orb invoice portal, Orb renders an Adyen Web Drop-in that displays every payment method enabled on your merchant account, such as cards, ACH, PayPal, Klarna, and Bancontact. To add or remove methods, enable them on your Adyen merchant account; no changes are needed in Orb.

​
3D Secure authentication

When a payment in the invoice portal requires 3D Secure (SCA), the Drop-in completes the challenge inline as part of the checkout, so no additional setup is needed. Off-session auto-collection charges run without customer interaction, so a stored payment method that would require a 3D Secure challenge to authenticate cannot be charged off-session.

​
Saving payment methods

The Drop-in can save a customer’s payment method for future use. Whether the customer is shown a “save this payment method” option is controlled by your account’s payment settings:
  • Always save: the payment method is stored without prompting.
  • Ask the customer: the Drop-in renders a consent checkbox.
  • Never save: no method is stored.
Saved payment methods are tokenized by Adyen and associated with the Orb customer, and become the method Orb charges for auto-collection.

​
Managing payment methods via the API

In addition to the portal’s “save” flow, you can attach, list, and remove a customer’s stored Adyen payment methods directly through the API, and choose which one is the customer’s default. This is useful when you already hold an Adyen stored payment method (a storedPaymentMethodId) for a customer and want Orb to charge it during auto-collection.
You designate the default payment method for Adyen customers. Tell Orb which stored method is the customer’s default, either by passing customer_default: true when attaching it or by setting default_payment_method_id on the customer. Orb charges that designated default during auto-collection.
A payment method object is intentionally minimal:
FieldDescription
idThe Orb-assigned identifier for the payment method.
payment_method_typeThe underlying instrument type, one of card, us_bank_account, link, amazon_pay, or crypto.
provider_typeThe payment provider the method belongs to (e.g. adyen).
external_payment_method_idThe identifier of this method in the payment provider (for Adyen, the storedPaymentMethodId).
customer_idThe Orb customer the method is attached to.
defaultWhether this is the customer’s default payment method.
created_atWhen the method was created in Orb.

​
Attaching a payment method

Attach an Adyen stored payment method to a customer with POST /payment_methods. Provide exactly one of customer_id or external_customer_id, and set customer_default to true to make it the customer’s default in the same call. Attaching the same external_payment_method_id to a customer twice returns a 409. 
curl -X POST https://api.withorb.com/v1/payment_methods \
  -H "Authorization: Bearer $ORB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_type": "adyen",
    "external_payment_method_id": "<adyen_stored_payment_method_id>",
    "customer_id": "<orb_customer_id>",
    "customer_default": true
  }'

​
Listing payment methods

List a customer’s payment methods (most recently created first) with GET /payment_methods. One of customer_id or external_customer_id is required. The response follows Orb’s standard pagination format. 
curl https://api.withorb.com/v1/payment_methods?customer_id=<orb_customer_id> \
  -H "Authorization: Bearer $ORB_TOKEN"

​
Removing a payment method

Delete a payment method with DELETE /payment_methods/{payment_method_id}. This is a soft delete; if the method was the customer’s default, the customer is left with no default. 
curl -X DELETE https://api.withorb.com/v1/payment_methods/<payment_method_id> \
  -H "Authorization: Bearer $ORB_TOKEN"

​
Setting the default payment method

A customer’s default payment method is what Orb charges during auto-collection. The customer resource exposes it as default_payment_method, and you can set or clear it on PUT /customers with default_payment_method_id. Pass a payment method ID to set the default, or null to clear it. The payment method must belong to that customer. 
curl -X PUT https://api.withorb.com/v1/customers/<orb_customer_id> \
  -H "Authorization: Bearer $ORB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "default_payment_method_id": "<payment_method_id>" }'
Attaching, removing, or changing the default emits the corresponding payment_method.created, payment_method.deleted, and customer.edited webhooks so your systems stay in sync.

​
Auto-collection

When auto-collection is enabled, Orb charges the customer’s default Adyen payment method off-session on the invoice due date. Payment results are reconciled asynchronously through Adyen webhooks, and the invoice’s status, timeline, and invoice.payment_succeeded / invoice.payment_failed webhooks reflect the outcome.

​
Refunds

Refunds issued in Adyen are reflected on the corresponding Orb invoice. To return funds to a customer, issue the refund in Adyen, then follow the refund credit note workflow to keep your Orb accounts receivable and balances aligned.