Skip to main content

Card handover (API-only integration guide)

This guide is for payment gateways and PCI-compliant merchants that want a direct API integration with Open Fabric (no Web SDK) and can fetch/process card details server-side.

With the card handover flow:

  • You create a transaction via Open Fabric.
  • You redirect the customer to Open Fabric for approval.
  • On approval, you receive a txn_card_token (card fetch token) via redirect and/or webhook.
  • Your backend exchanges that token for one-time card details and charges them using your existing card processing setup.

Prerequisites​

  • Client ID / Client Secret for Open Fabric OAuth

Flow and system interactions​

Integration steps​

Step 1: Get an access token​

Your backend generates an access token using your Open Fabric credentials (client ID and client secret). The access token is needed to initialize the Merchant SDK.

See API reference in our API Reference for more details.

Recommended scopes:

  • resources/transactions.read
  • resources/transactions.create
  • resources/cards.read
tip

The access token is valid for a limited time. Cache and reuse it on your server to reduce latency and avoid unnecessary token requests.

Step 2: Create a Transaction​

See the Create Merchant Transaction API in our API Reference for more details.

The API responds with a payment_redirect_web_url.

Step 3: Redirect customer to Open Fabric for approval​

Redirect to payment_redirect_web_url received in the previous step, so that the Payment Method can approve the tranasction.

Step 4: Handle redirect back (extract txn_card_token)​

On approval, Open Fabric redirects back to your partner_redirect_success_url and includes txn_card_token. On failure, Open Fabric redirects back to your partner_redirect_fail_url.

You will also receive a webhook notification, see:

Step 5: Retrieve card details​

Now you call Open Fabric to retrieve a transaction-specific virtual card using the txn_card_token.

See Retrieve card details in our API Reference for more details.

warning

This should be a server-to-server call, given we need the card details to be handled securely.

Step 6: Charge the one-time card​

Charge the card details using your existing payment gateway/card processor.

Step 7: Respond to the Merchant/Customer​

After the card has been charged, redirect the customer back to the merchant with the appropriate status.

Additional use cases​

Refunds​

Issue refunds using your existing gateway/card processor refund flow (refund against the card transaction). You do not need to integrate separately with Open Fabric or the Payment Method to issue refunds. Refunds against virtual cards can be issued up to 180 days.

Delayed payment approvals​

In some scenarios a payment approval can be delayed, for instance when a Payment Method need to approve a loan towards the customer. Redirection back to your website can also fail for other reasons, for instance when the customer closed their browser or lost internet connectivity. For such cases, please consume the our notifications:

Get transaction status​

Use our Get transaction status API to get the current transaction status.