Skip to main content

PG token handover (API-only integration guide)

This guide is for payment gateways and merchants that want a direct API integration with Open Fabric (no Web SDK) and prefer Open Fabric to tokenize the one-time card with their payment gateway.

With the PG token handover flow:

  • You create a transaction via Open Fabric.
  • You redirect the customer to Open Fabric for approval.
  • On approval, Open Fabric creates a one-time virtual card, submits it to your payment gateway, and returns a token via redirect and webhook notification.
  • You charge that token using your existing gateway integration.

Prerequisites​

  • Client ID / Client Secret for Open Fabric OAuth
  • Your payment gateway credentials configured with Open Fabric (so we can create tokens on your behalf)

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).

See API reference in our API Reference for more details.

Recommended scopes:

  • resources/transactions.read
  • resources/transactions.create
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 (PG token flow)​

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

Set:

  • pg_name: your gateway identifier
  • pg_flow: tokenization
Example Request
{
  "partner_reference_id": "P1293201980299030",
  "partner_redirect_success_url": "https://merchant.example/success?state=PAID",
  "partner_redirect_fail_url": "https://merchant.example/fail?state=CANCELLED",
  "amount": 1200.1,
  "currency": "PHP",
  "pg_name": "paymaya",
  "pg_flow": "tokenization",
  "customer_info": {
    "first_name": "John",
    "last_name": "Doe"
  },
  "transaction_details": {}
}

The API responds with a payment_redirect_web_url.

Step 3: Redirect customer to Open Fabric for approval​

Redirect the customer to the returned payment_redirect_web_url.

Step 4: Handle redirect back​

When a payment is approved by the Payment Method, we will create a virtual card and pass the card details on to the Payment Gateway in return for a unique pg_token.
On approval, Open Fabric redirects back to your partner_redirect_success_url and includes pg_token. On failure, Open Fabric redirects back to your partner_redirect_fail_url.

You will also receive a webhook notification, see:

Step 5: Charge using your payment gateway​

Charge the token (pg_token) using your existing gateway integration.

Step 6: Respond to the Merchant/Customer​

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

Optional capabilities​

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.