Skip to main content
API docs by Redocly

Open Fabric APIs (v1)

Download OpenAPI specification:Download

Open Fabric API: api@openfabric.co URL: https://openfabric.co

Open Fabric APIs, v1

Authentication

Our APIs use an authentication scheme based on OAuth 2.0. See Authentication for more details.

Request access token

Request Body schema: application/x-www-form-urlencoded
grant_type
required
string
Value: "client_credentials"
scope
string

Space-separated API scopes for the token. See API Access Scopes for the list of available scopes.

If not provided, the access token will be generated with all scopes.

Responses

Request samples

Content type
application/x-www-form-urlencoded
grant_type=client_credentials&scope=txn.c%20txn.r

Response samples

Content type
application/json
{
  • "access_token": "eyJz9sdfsdfsdfsd",
  • "id_token": "dmcxd329ujdmkemkd349r",
  • "token_type": "Bearer",
  • "expires_in": 3600
}

Provision Account

API used to provision new accounts. See Provision account for more details.

Provision a new account

This API can be used to provision a new account or virtual card.

See Own App Tokens, Digital Wallet Tokens or Virtual Cards for more details.

header Parameters
Idempotency-Key
string

Unique value submitted by the partner to ensure idempotent request during provisioning.

Request Body schema: application/json
required
type
string (PbaProvisionType)
Enum: "nfc_device_token" "static_token" "push_provision"
payment_network
string (PbaPaymentNetwork)
Enum: "mastercard" "visa"

The payment network of the transaction

tenant_customer_ref
required
string

Customer identifier in your system

tenant_account_ref
required
string <= 64 characters

Account identifier of the customer in your system

tenant_token_ref
string

Token identifier in your system. Required if Idempotency-Key is not set.

If set, this will be passed to card network as the issuer token identifier. If not set, the Idempotency-Key will be used instead.

wallet_id
string

Secure device wallet identifier. Required for Own App Tokens.

Can be obtained by reading wallet.walletId in the NFC SDK.

device_name
string

Name of the device

tenant_account_device_ref
string <= 32 characters

Device identifier in your system

billing_currency
string = 3 characters ^[A-Z]*$

Billing currency (ISO 4217 currency code). If not passed, the default billing currency will be used.

object (Address)
instrument
string (PbaProvisionInstrument)
Enum: "manual_card_entry" "google_pay" "samsung_pay"
  • manual_card_entry for Virtual Cards.
  • google_pay, or samsung_pay for Digital Wallet Tokens.
  • Not required for Own App Tokens.
card_name
string

Name of the card

card_program_id
string <uuid>

Card Program ID. If not provided, the tenant's default card program will be used.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "static_token",
  • "tenant_customer_ref": "customer-00000000000001",
  • "tenant_account_ref": "FR00000000000001",
  • "tenant_token_ref": "TOK000000000000001",
  • "instrument": "manual_card_entry"
}

Response samples

Content type
application/json
Example
{
  • "tenant_account_ref": "FR00000000000001",
  • "tenant_customer_ref": "customer-00000000000001",
  • "of_customer_id": "40095c2f-d391-4e06-94d9-cf0b3191c548",
  • "of_account_id": "5bafb9bc-9573-4acf-b686-04bf62c81af8",
  • "customer_id": "40095c2f-d391-4e06-94d9-cf0b3191c548",
  • "account_id": "5bafb9bc-9573-4acf-b686-04bf62c81af8",
  • "static_token_id": "180106f9-8177-42fa-99bf-23ae8d785636",
  • "instrument": "manual_card_entry",
  • "status": "active",
  • "locked": false,
  • "created_at": "2026-03-10T10:27:58.253Z",
  • "updated_at": "2026-03-10T10:27:58.253Z"
}

Provision an account for an existing card

This API can be used to provision an account for an existing card.

See Own App Tokens - Tokenize an existing card for more details.

Request Body schema: application/json
required
digital_wallet
required
string (DigitalWallet)
Enum: "issuer" "google_pay" "apple_pay" "samsung_pay"

Digital wallet provider. Use issuer for Own App Tokens.

tenant_customer_ref
required
string

Customer identifier in your system

issuer_card_id
required
string

Issuer card identifier retrieved from your CMS

wallet_id
required
string

Secure device wallet identifier

issuer_authentication_data
string

Issuer authentication value to be used in the tokenization request with the token service provider (TSP). The authentication value is specific to the token service provider (TSP), and it should be PGP-encrypted with Open Fabric’s shared public key, Base64-encoded when sending to Open Fabric

encrypted_card_data
required
string

Card data JSON encrypted with Open Fabric’s shared public key, Base64-encoded

object (Address)

Responses

Request samples

Content type
application/json
{
  • "digital_wallet": "issuer",
  • "tenant_customer_ref": "customer-00000000000001",
  • "issuer_card_id": "507e8c90-3cfc-44ee-b701-0630067eb44fa5e9351a-0a6",
  • "wallet_id": "507e8c90-3cfc-44ee-b701-0630067eb44fa5e9351a-0a6",
  • "encrypted_card_data": "eyJ4NWMiOlsiTUlJQzNqQ0NBY2FnQXdJQkFnSUpBT1FDdnc2..."
}

Response samples

Content type
application/json
{
  • "wallet_id": "507e8c90-3cfc-44ee-b701-0630067eb44fa5e9351a-0a6",
  • "provisioning_data": {
    }
}

Manage Secure Device Wallets

APIs used to manage the lifecycle of secure device wallets. See Lifecycle management for more details.

Lock a secure device wallet

You can use this API to lock a secure device wallet. This will temporarily block payments and other functionalities of the wallet.

path Parameters
id
required
string <uuid>

Secure device wallet identifier

Request Body schema: application/json
required
reason_code
required
string (PbaLockWalletReasonCode)
Enum: "device_stolen" "device_lost" "suspected_fraud" "other"
reason
required
string

Reason for changing the status

Responses

Request samples

Content type
application/json
{
  • "reason_code": "suspected_fraud",
  • "reason": "Requested by fraud team"
}

Response samples

Content type
application/json
{
  • "wallet_id": "6d6a9511-c4d3-4bc0-8d02-a054e8a5559112d56356-efa",
  • "status": "suspended",
  • "status_timestamp": "2026-03-17T12:00:00.000Z",
  • "suspended_by": [
    ]
}

Unlock secure device wallet

You can use this API to unlock a secure device wallet.

path Parameters
id
required
string <uuid>

Secure device wallet identifier

Request Body schema: application/json
required
reason_code
required
string (PbaUnlockWalletReasonCode)
Enum: "device_found" "not_fraud" "other"
reason
required
string

Reason for changing the status

Responses

Request samples

Content type
application/json
{
  • "reason_code": "not_fraud",
  • "reason": "Customer has been verified by fraud team"
}

Response samples

Content type
application/json
{
  • "wallet_id": "6d6a9511-c4d3-4bc0-8d02-a054e8a5559112d56356-efa",
  • "status": "active",
  • "status_timestamp": "2026-03-17T12:00:00.000Z",
  • "suspended_by": [ ]
}

Delete secure device wallet

You can use this API to delete a secure device wallet.

Warning A secure device wallet deletion cannot be undone.

path Parameters
id
required
string <uuid>

Secure device wallet identifier

Request Body schema: application/json
required
reason_code
required
string (PbaLockWalletReasonCode)
Enum: "device_stolen" "device_lost" "suspected_fraud" "other"
reason
required
string

Reason for changing the status

Responses

Request samples

Content type
application/json
{
  • "reason_code": "device_stolen",
  • "reason": "Requested by fraud team"
}

Response samples

Content type
application/json
{
  • "wallet_id": "6d6a9511-c4d3-4bc0-8d02-a054e8a5559112d56356-efa",
  • "status": "deactivated",
  • "status_timestamp": "2026-03-17T12:00:00.000Z",
  • "suspended_by": [ ]
}

Retrieve Card Details

APIs used to retrieve sensitive virtual card details. See Display card details for more details.

Get card fetch token

This API can be used to get a card fetch token for a specific virtual card.

Request Body schema: application/json
required
static_token_id
required
string <uuid>

Open Fabric's static token id for the card.

account_id
required
string

Account identifier in Open Fabric. Must match the account_id associated with the static_token_id.

card_encryption_key
string

The public key (PEM format) to be used when encrypting the card detail. When this field is not specified, no encryption will be performed to secure the card detail.

card_encryption_algo
string (CardEncryptionAlgo)
Enum: "rsa_oaep" "ecc_ecies"

The algorithm to be used when encrypting the card detail. If specified, you must send the value of the public key file (PEM format) in the card_encryption_key field.

Responses

Request samples

Content type
application/json
Example
{
  • "static_token_id": "c2319421-f0e8-4dd6-a099-124c5a3c6592",
  • "account_id": "436605a1-271d-49a7-80f0-bcaf095cdd6a",
  • "card_encryption_key": "-----BEGIN PUBLIC KEY-----\nMII…\n-----END PUBLIC KEY-----",
  • "card_encryption_algo": "rsa_oaep"
}

Response samples

Content type
application/json
{
  • "card_fetch_token": "eyJhbGciOiJIUzI1...adQssw5c"
}

Retrieve card details

This API can be used to retrieve sensitive details of a virtual card.

Warning Please be aware that your system might be subject to a higher level of PCI DSS certification if you use this API.

Request Body schema: application/json
required
card_fetch_token
required
string

The card fetch token obtained using the Get card fetch token request

fetch_cvv
boolean
Default: true

It will be used to return cvv in response or not. By default its true

Responses

Request samples

Content type
application/json
{
  • "card_fetch_token": "YTZkYmJkYWItMWI3ZC00MzNhLTkzOWEtZjYzYzkwMjJmODMz"
}

Response samples

Content type
application/json
{
  • "provider": "mastercard",
  • "card_reference_id": "dpan_9ku2ouUwBCHW3pYSevRE72XD5kYGSQfMKuhBjWLkqAue_2Eu6hV4BwMfng",
  • "card_number": "5281724086788282",
  • "redacted_number": "XXXXXXXXXXXX8282",
  • "cvv": "111",
  • "expiry_month": "12",
  • "expiry_year": "25",
  • "message": ""
}

Display Virtual Cards

APIs used to display virtual card details securely. See Display virtual cards for more details.

Create card details widget

Generates a short-lived widget URL for displaying card details (PAN, expiry, CVV) in an iframe or webview. The widget URL is time-limited and single-use.

Request Body schema: application/json
required
static_token_id
string

Either static_token_id or card_fetch_token must be provided.

card_fetch_token
string

Either static_token_id or card_fetch_token must be provided.

card_art_asset_id
string <uuid>

Identifier of a pre-uploaded card art asset. Obtained from the asset upload API. Mutually exclusive with card_art_base64.

card_art_base64
string <= 204800 characters

Base64 encoded card art image.

Max 150KB decoded. Recommended dimensions: 340x214px (or 1.586:1 aspect ratio).

Mutually exclusive with card_art_asset_id.

card_art_content_type
string (CardArtContentType)
Enum: "image/png" "image/jpeg" "image/webp"

MIME type of the card art image

text_color
string^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$

Hex color code for text displayed on the card widget (e.g., "#FFFFFF" for white). Optional, defaults to black if not provided.

Responses

Request samples

Content type
application/json
Example
{
  • "card_fetch_token": "eyJhbGciOiJIUzI1...",
  • "card_art_asset_id": "7f3a2b1c-9d4e-5f6a-8b7c-0d1e2f3a4b5c"
}

Response samples

Content type
application/json
{}

Upload card art asset

Uploads a card art image for reuse across multiple widget sessions. Returns an asset_id that can be referenced in the widget creation API.

Request Body schema: application/json
required
card_art_base64
required
string <= 204800 characters

Base64 encoded card art image.

Max 150KB decoded. Recommended dimensions: 340x214px (or 1.586:1 aspect ratio).

card_art_content_type
required
string (CardArtContentType)
Enum: "image/png" "image/jpeg" "image/webp"

MIME type of the card art image

card_art_asset_name
string

Optional human-readable label for the asset (e.g., "Premium Black", "Student Card").

Responses

Request samples

Content type
application/json
{
  • "card_art_base64": "iVBORw0KGgoAAAANSUhEUgAAAVQAAADW...",
  • "card_art_content_type": "image/png",
  • "card_art_asset_name": "Premium Black"
}

Response samples

Content type
application/json
{
  • "card_art_asset_id": "f202723b-2873-4618-a10b-6cec3b9c52f7",
  • "card_art_asset_name": "Premium Black",
  • "card_art_content_type": "image/png",
  • "size_bytes": 6988,
  • "created_at": "2026-03-16T09:23:48.684Z"
}

List card art assets

Returns all card art assets uploaded by the tenant.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Delete card art asset

Deletes a previously uploaded card art asset. Existing widget sessions that already resolved this asset are unaffected.

path Parameters
asset_id
required
string <uuid>

Identifier of card art asset.

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "details": [
    ]
}

Manage Virtual Cards

APIs used to manage virtual cards. See Manage virtual cards for more details.

List virtual cards

This API can be used to list all virtual cards belonging to a customer.

query Parameters
tenant_customer_ref
string

Filter by tenant customer ref

tenant_account_ref
string

Filter by tenant account ref

instrument
string (RoutingDataInitializingInstrument)
Enum: "web_checkout" "unilateral_checkout" "one_click_checkout" "recurring" "tenant_recurring" "pba_static_token" "qrph" "sgqr" "vietqr" "tap_and_pay" "manual_card_entry" "google_pay" "samsung_pay"

Filter by instrument

status
string (StaticTokenStatus)
Enum: "active" "inactive" "deactivated"

Filter by status

locked
boolean

Filter by lock status

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get virtual card

This API can be used to get details of a specific virtual card.

path Parameters
id
required
string

Static token identifier in Open Fabric representing a Virtual Card

Responses

Response samples

Content type
application/json
{
  • "id": "4fbc4775-466c-4d21-bb8c-95f3ef9ffbea",
  • "tenant_account_ref": "FR00000000000001",
  • "tenant_customer_ref": "customer-00000000000001",
  • "tenant_token_ref": "TOK000000000000001",
  • "tsp_token_ref": "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
  • "account_id": "c6045eed-b5cb-48f0-8321-b924a8e8f808",
  • "customer_id": "5b3aae19-16b5-4aca-81b5-5d72a168c496",
  • "dpan_redacted_number": "512*********9708",
  • "dpan_expiry": {
    },
  • "instrument": "manual_card_entry",
  • "status": "active",
  • "locked": false,
  • "created_at": "2026-03-16T07:39:09.317Z",
  • "updated_at": "2026-03-16T07:39:09.317Z"
}

Update virtual card

This API can be used to lock or unlock a specific virtual card.

path Parameters
id
required
string

Static token identifier in Open Fabric representing a Virtual Card

Request Body schema: application/json
required
lock_status
required
string (StaticTokenLockStatus)
Enum: "locked" "unlocked"

Responses

Request samples

Content type
application/json
Example
{
  • "lock_status": "locked"
}

Response samples

Content type
application/json
Example
{
  • "id": "4fbc4775-466c-4d21-bb8c-95f3ef9ffbea",
  • "tenant_account_ref": "FR00000000000001",
  • "tenant_customer_ref": "customer-00000000000001",
  • "tenant_token_ref": "TOK000000000000001",
  • "tsp_token_ref": "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
  • "account_id": "c6045eed-b5cb-48f0-8321-b924a8e8f808",
  • "customer_id": "5b3aae19-16b5-4aca-81b5-5d72a168c496",
  • "dpan_redacted_number": "512*********9708",
  • "dpan_expiry": {
    },
  • "instrument": "manual_card_entry",
  • "status": "active",
  • "locked": true,
  • "created_at": "2026-03-16T07:39:09.317Z",
  • "updated_at": "2026-03-16T07:39:09.317Z"
}

Delete virtual card

This API can be used to deactivate a specific virtual card.

Warning This action is permanent (cannot be undone) and requires the virtual card to be locked first before deleting.

path Parameters
id
required
string

Static token identifier in Open Fabric representing a Virtual Card

Request Body schema: application/json
required
reason_text
string
reason_code
string (PbaCustomerDpanSuspendReasonCode)
Enum: "device_lost" "device_stolen" "suspected_fraud" "other"

Responses

Request samples

Content type
application/json
{
  • "reason_text": "Customer reported device is lost",
  • "reason_code": "device_lost"
}

Response samples

Content type
application/json
{
  • "id": "4fbc4775-466c-4d21-bb8c-95f3ef9ffbea",
  • "tenant_account_ref": "FR00000000000001",
  • "tenant_customer_ref": "customer-00000000000001",
  • "tenant_token_ref": "TOK000000000000001",
  • "tsp_token_ref": "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
  • "account_id": "c6045eed-b5cb-48f0-8321-b924a8e8f808",
  • "customer_id": "5b3aae19-16b5-4aca-81b5-5d72a168c496",
  • "dpan_redacted_number": "512*********9708",
  • "dpan_expiry": {
    },
  • "instrument": "manual_card_entry",
  • "status": "deactivated",
  • "locked": true,
  • "created_at": "2026-03-16T07:39:09.317Z",
  • "updated_at": "2026-03-16T07:39:09.317Z"
}

Token Update Notifications

Notifications sent to your backend when tokens change state within a secure device wallet or when a tokenized transaction authorization occurs within the wallet.

See Token update notifications for more details.

OutToken activated notification

This notification is sent when an account or card was successfully tokenized and activated in the secure device wallet.

Request Body schema: application/json
required
notification_id
required
string <uuid>

The unique identifier for the notification

type
required
string
Value: "v1:wallet:token:activated"
created_at
required
string <date-time>

The creation timestamp of the notification in ISO 8601 format

required
object (WalletTokenActivatedEventNotificationPayload)

Base schema for wallet token status change notifications data

Responses

Request samples

Content type
application/json
{
  • "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
  • "type": "v1:wallet:token:activated",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

OutToken suspended notification

This notification is sent when the tokenized account or card is suspended in the secure device wallet.

Request Body schema: application/json
required
notification_id
required
string <uuid>

The unique identifier for the notification

type
required
string
Value: "v1:wallet:token:suspended"
created_at
required
string <date-time>

The creation timestamp of the notification in ISO 8601 format

required
object (WalletTokenSuspendedEventNotificationPayload)

Base schema for wallet token status change notifications data

Responses

Request samples

Content type
application/json
{
  • "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
  • "type": "v1:wallet:token:suspended",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

OutToken deleted notification

This notification is sent when the tokenized account or card is deleted from the secure device wallet.

Request Body schema: application/json
required
notification_id
required
string <uuid>

The unique identifier for the notification

type
required
string
Value: "v1:wallet:token:deleted"
created_at
required
string <date-time>

The creation timestamp of the notification in ISO 8601 format

required
object (WalletTokenDeletedEventNotificationPayload)

Base schema for wallet token status change notifications data

Responses

Request samples

Content type
application/json
{
  • "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
  • "type": "v1:wallet:token:deleted",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

OutTransaction authorization notification

This notification is sent when a transaction is authorized within the secure device wallet.

Request Body schema: application/json
required
notification_id
required
string <uuid>

The unique identifier for the notification

type
required
string
Value: "v1:wallet:transaction:authorization"
created_at
required
string <date-time>

The creation timestamp of the notification in ISO 8601 format

required
object (PbaWalletTransactionAuthorizedNotification)

v1:wallet:transaction:authorization

Responses

Request samples

Content type
application/json
{
  • "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
  • "type": "v1:wallet:transaction:authorization",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Authorization

APIs related to authorization messages. These are messages sent from our platform to your backend.

See Authorization message for more details.

OutAuthorization message

Real-time authorization messages sent to your backend for an approval/decline decision. The same schema is used for final authorizations and pre-authorizations.

See Authorization message for more details.

Request Body schema: application/json
required
card_program_id
string
transaction_id
required
string <uuid>

Transaction identifier in Open Fabric

network_transaction_ref
required
string

Transaction Reference received from the network

customer_id
required
string <uuid>

Customer identifier in Open Fabric

tenant_customer_ref
required
string

Customer identifier in your system

account_id
required
string <uuid>

Account identifier in Open Fabric

tenant_account_ref
required
string

Account identifier in your system

provision_id
required
string <uuid>

Provision identifier in Open Fabric.

This equals the:

  • static_token_id for Virtual Cards
  • device_id for Own App tokens
  • digital_token_id for Digital Wallet Tokens
provision_type
required
string (PbaAskForApprovalProvisionType)
Enum: "customer_account_device" "static_token" "google_pay" "samsung_pay" "apple_pay" "unknown"

Provision type in Open Fabric.

  • customer_account_device for Own App tokens
  • static_token for Virtual Cards
  • google_pay for Google Pay Tokens
  • samsung_pay for Samsung Pay Tokens
  • apple_pay for Apple Pay Tokens
  • unknown if the provision type is not known
device_id
string <uuid>

Deprecated. Use provision_id and provision_type instead. Device identifier in Open Fabric

static_token_id
string

Deprecated. Use provision_id and provision_type instead. Static token identifier in Open Fabric representing a Virtual Card

network_message_ref
required
string

Message reference received from the network

network_merchant_id
required
string

Merchant ID received from the network

network_merchant_name
required
string

Merchant name received from the network

network_merchant_outlet_address
required
string

Merchant outlet address received from the network

network_merchant_category_code
required
string

Merchant category code received from the network

network_acquirer_id
string

Merchant acquirer ID received from the network

network_merchant_city
string

Merchant city received from the network

network_merchant_terminal_id
string

Merchant terminal ID received from the network

partner_country_code
required
string = 2 characters

Country Code - ISO 3166 Alpha-2

required
object (PbaAskForApprovalAuthIndicator)
amount
required
number

Transaction amount in major units

currency
required
string

Transaction currency code (ISO 4217)

billing_amount
required
number

Billing amount in major units

billing_currency_code
required
string

Billing currency code (ISO 4217)

billing_exchange_rate
required
number

Exchange rate when calculating billing amount

settlement_amount
number

Settlement amount in major units

settlement_currency_code
string

Settlement currency code (ISO 4217)

settlement_exchange_rate
number

Exchange rate when calculating settlement amount

transaction_source
required
string (PbaAskForApprovalTransactionSource)
Enum: "ecommerce" "terminal"

The source of the transaction:

  • ecommerce for ecommerce transactions
  • terminal for terminal transactions
transaction_category
required
string (PbaTransactionCategory)
Enum: "high_risk_purchase" "recurring_payment" "transit" "automated_fuel_dispenser" "dynamic_currency_conversion" "cardholder_activated_terminal" "other"

The category of the transaction determined by Open Fabric

card_on_file
boolean

True indicates that this transaction is initiated from a card on file

payment_network
required
string (PbaPaymentNetwork)
Enum: "mastercard" "visa"

The payment network of the transaction

object (PbaAskForApprovalVerificationData)
token_requestor_id
string

Indicates whether the transaction originated from your own app or a third-party wallet (e.g. Google Pay, Samsung Pay, Apple Pay).

object (AuthPolicyEvaluateResponse)

Response from policy evaluation

network_message_timestamp
string <date-time>

Original timestamp from the card network message

Responses

Request samples

Content type
application/json
Example
{
  • "transaction_id": "f0cadbba-6f2f-4fc0-a471-72b2d6a62aaf",
  • "network_transaction_ref": "MCC9745460320",
  • "customer_id": "218f3096-8445-4898-a737-ec68f563a8eb",
  • "tenant_customer_ref": "ZAPPCONSUYT5VmbJCs47",
  • "account_id": "3dfc28d5-ed01-438f-8c4d-ca387b6db65e",
  • "tenant_account_ref": "FR123456789054001111012345672511",
  • "provision_id": "407957cf-d009-44ac-84bc-634d27fa5f4d",
  • "provision_type": "customer_account_device",
  • "device_id": "407957cf-d009-44ac-84bc-634d27fa5f4d",
  • "network_message_ref": "386217",
  • "network_merchant_id": "ABC123TESTMTF19",
  • "network_merchant_name": "DAIDOMON",
  • "network_merchant_outlet_address": "MyCity, US",
  • "network_merchant_category_code": "5999",
  • "network_acquirer_id": "000003",
  • "network_merchant_city": "MyCity",
  • "network_merchant_terminal_id": "MTF TEST",
  • "partner_country_code": "US",
  • "auth_indicator": {
    },
  • "amount": 25,
  • "currency": "EUR",
  • "billing_amount": 30.04,
  • "billing_currency_code": "USD",
  • "billing_exchange_rate": 1.20149,
  • "settlement_amount": 30.04,
  • "settlement_currency_code": "USD",
  • "settlement_exchange_rate": 1.20149,
  • "transaction_source": "terminal",
  • "transaction_category": "cardholder_activated_terminal",
  • "card_on_file": false,
  • "payment_network": "mastercard",
  • "verification_data": {
    },
  • "token_requestor_id": "12345678901"
}

Response samples

Content type
application/json
Example
{
  • "tenant_reference_id": "4d65a071-a796-4864-b2b4-00d7015f6275",
  • "approved_amount": 25,
  • "authorization_code": "5M8DS2",
  • "status": "approved"
}

Ledger Operations

Ledger operations that Open Fabric calls on your backend to apply balance changes (debit/credit/hold/release).

See Ledger APIs for more details.

OutDebit balance

debit_balance: Deduct funds from a customer’s balance for settlement.

Request Body schema: application/json
required
transaction_id
required
string

Unique identifier for the transaction

tenant_account_ref
required
string

Identifier of the tenant account

idempotency_key
required
string

Unique identifier to prevent duplicate operations

object (BalanceAmount)

Amount object used in balance operations

of_action_ref
required
string

OpenFabric reference identifier for the operation

tenant_balance_ref
string

Reference of the exact balance to be debited (used in refund reversal)

network_message_timestamp
string <date-time>

Original timestamp from the card network message

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "string",
  • "tenant_account_ref": "string",
  • "idempotency_key": "string",
  • "amount": {
    },
  • "of_action_ref": "string",
  • "tenant_balance_ref": "string",
  • "network_message_timestamp": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tenant_balance_ref": "string",
  • "available_balance": {
    },
  • "tenant_action_ref": "string",
  • "error": {
    }
}

OutCredit balance

credit_balance: Add funds to a customer’s balance (for refunds or adjustments).

Request Body schema: application/json
required
transaction_id
required
string

Unique identifier for the transaction

tenant_account_ref
required
string

Identifier of the tenant account

idempotency_key
required
string

Unique identifier to prevent duplicate operations

object (BalanceAmount)

Amount object used in balance operations

of_action_ref
required
string

OpenFabric reference identifier for the operation

tenant_balance_ref
string

Reference of the exact balance to be credited (used in auth reversal)

network_message_timestamp
string <date-time>

Original timestamp from the card network message

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "string",
  • "tenant_account_ref": "string",
  • "idempotency_key": "string",
  • "amount": {
    },
  • "of_action_ref": "string",
  • "tenant_balance_ref": "string",
  • "network_message_timestamp": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tenant_balance_ref": "string",
  • "available_balance": {
    },
  • "tenant_action_ref": "string",
  • "error": {
    }
}

OutHold balance

hold_balance: Place a hold on funds in a customer’s balance (pre-authorization).

Request Body schema: application/json
required
transaction_id
required
string

Unique identifier for the transaction

tenant_account_ref
required
string

Identifier of the tenant account

idempotency_key
required
string

Unique identifier to prevent duplicate operations

object (BalanceAmount)

Amount object used in balance operations

of_action_ref
required
string

OpenFabric reference identifier for the operation

tenant_hold_balance_ref
string

Reference of the hold funds balance to be increased (used in pre-auth incremental)

network_message_timestamp
string <date-time>

Original timestamp from the card network message

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "string",
  • "tenant_account_ref": "string",
  • "idempotency_key": "string",
  • "amount": {
    },
  • "of_action_ref": "string",
  • "tenant_hold_balance_ref": "string",
  • "network_message_timestamp": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tenant_hold_balance_ref": "string",
  • "available_balance": {
    },
  • "tenant_action_ref": "string",
  • "error": {
    }
}

OutRestore balance

restore_balance: Release previously held funds back to available balance.

Request Body schema: application/json
required
transaction_id
required
string

Unique identifier for the transaction

tenant_account_ref
required
string

Identifier of the tenant account

idempotency_key
required
string

Unique identifier to prevent duplicate operations

object (BalanceAmount)

Amount object used in balance operations

of_action_ref
required
string

OpenFabric reference identifier for the operation

tenant_hold_balance_ref
required
string

Reference of the hold funds balance to be released (required)

network_message_timestamp
string <date-time>

Original timestamp from the card network message

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "string",
  • "tenant_account_ref": "string",
  • "idempotency_key": "string",
  • "amount": {
    },
  • "of_action_ref": "string",
  • "tenant_hold_balance_ref": "string",
  • "network_message_timestamp": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tenant_balance_ref": "string",
  • "available_balance": {
    },
  • "tenant_action_ref": "string",
  • "error": {
    }
}

OutDebit hold balance

debit_hold_balance: Deduct an amount from previously held funds (created with hold_balance).

Request Body schema: application/json
required
transaction_id
required
string

Unique identifier for the transaction

tenant_account_ref
required
string

Identifier of the tenant account

idempotency_key
required
string

Unique identifier to prevent duplicate operations

object (BalanceAmount)

Amount object used in balance operations

of_action_ref
required
string

OpenFabric reference identifier for the operation

tenant_hold_balance_ref
required
string

Reference of the hold funds balance to be debited (required)

network_message_timestamp
string <date-time>

Original timestamp from the card network message

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "string",
  • "tenant_account_ref": "string",
  • "idempotency_key": "string",
  • "amount": {
    },
  • "of_action_ref": "string",
  • "tenant_hold_balance_ref": "string",
  • "network_message_timestamp": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tenant_hold_balance_ref": "string",
  • "hold_balance": {
    },
  • "tenant_action_ref": "string",
  • "error": {
    }
}

OutCredit hold balance

credit_hold_balance: Add an amount to previously held funds (created with hold_balance).

Request Body schema: application/json
required
transaction_id
required
string

Unique identifier for the transaction

tenant_account_ref
required
string

Identifier of the tenant account

idempotency_key
required
string

Unique identifier to prevent duplicate operations

object (BalanceAmount)

Amount object used in balance operations

of_action_ref
required
string

OpenFabric reference identifier for the operation

tenant_hold_balance_ref
required
string

Reference of the hold funds balance to be credited (required)

network_message_timestamp
string <date-time>

Original timestamp from the card network message

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "string",
  • "tenant_account_ref": "string",
  • "idempotency_key": "string",
  • "amount": {
    },
  • "of_action_ref": "string",
  • "tenant_hold_balance_ref": "string",
  • "network_message_timestamp": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "tenant_hold_balance_ref": "string",
  • "hold_balance": {
    },
  • "tenant_action_ref": "string",
  • "error": {
    }
}

Reversal Notifications

Notifications related to reversals. These are messages sent from our platform to your backend.

See Reversal notifications for more details.

OutFinal authorization reversal notification

Notification sent when a previously approved final authorization is reversed.

See Reversal notifications for more details.

Request Body schema: application/json
required
notification_id
required
string <uuid>

The unique identifier for the notification

type
required
string
Value: "v1:pba:transaction:final_auth_reversed"
created_at
required
string <date-time>

The creation timestamp of the notification in ISO 8601 format

required
object (FinalAuthReversalNotification)

v1:pba:transaction:final_auth_reversed

Responses

Request samples

Content type
application/json
{
  • "notification_id": "b16a7072-3deb-46d3-aad0-5b95da03e8e4",
  • "type": "v1:pba:transaction:final_auth_reversed",
  • "created_at": "2026-03-21T00:23:27Z",
  • "data": {
    }
}

OutPre-authorization reversal notification

Notification sent when a previously approved pre-authorization is reversed.

See Reversal notifications for more details.

Request Body schema: application/json
required
notification_id
required
string <uuid>

The unique identifier for the notification

type
required
string
Value: "v1:pba:transaction:pre_auth_reversed"
created_at
required
string <date-time>

The creation timestamp of the notification in ISO 8601 format

required
object (PreAuthReversalNotification)

v1:pba:transaction:pre_auth_reversed

Responses

Request samples

Content type
application/json
{
  • "notification_id": "b16a7072-3deb-46d3-aad0-5b95da03e8e4",
  • "type": "v1:pba:transaction:pre_auth_reversed",
  • "created_at": "2026-03-21T00:23:27Z",
  • "data": {
    }
}

OutAuthorization failed notification

Notification sent when an authorization could not be completed successfully (e.g. due to timeout or non-200 from your approval endpoint) and was declined on your behalf.

See Reversal notifications for more details.

Request Body schema: application/json
required
notification_id
required
string <uuid>

The unique identifier for the notification

type
required
string
Value: "v1:pba:transaction:authorization_failed"
created_at
required
string <date-time>

The creation timestamp of the notification in ISO 8601 format

required
object (PbaAuthorizationFailedNotification)

v1:pba:transaction:authorization_failed

Responses

Request samples

Content type
application/json
{
  • "notification_id": "3e6dd7ab-3360-4269-821e-a591bc94232c",
  • "type": "v1:pba:transaction:authorization_failed",
  • "created_at": "2024-06-06T18:47:21.175Z",
  • "data": {
    }
}

3D Secure

APIs and messages used to complete 3D Secure challenges during payment processing.

See Handle 3D Secure Payments for more details.

OutOut-of-band (OOB) challenge request

This notification is sent to your backend when a 3D Secure challenge requires an out-of-band (OOB) challenge to be completed.

See 3DS Out of Band (OOB) challenge flow for more details.

Request Body schema: application/json
required
three_ds_challenge_id
required
string

3DS Request ID in Open Fabric

tenant_customer_ref
required
string

Customer identifier in your system

customer_id
required
string

Customer identifier in Open Fabric

tenant_account_ref
required
string

Account identifier in your system

account_id
required
string

Account identifier in Open Fabric

static_token_id
required
string

Static token identifier in Open Fabric representing a Virtual Card

merchant_name
required
string

Name of the merchant

transaction_amount
number

Amount of the transaction. If not present or 0, it is a non-payment 3DS authentication.

transaction_currency
string

Currency code for the transaction (e.g., USD, EUR). Not present for non-payment 3DS authentications.

creation_time
required
string <date-time>

Creation time of the 3DS request in ISO 8601 format

Responses

Request samples

Content type
application/json
{
  • "three_ds_challenge_id": "string",
  • "tenant_customer_ref": "string",
  • "customer_id": "string",
  • "tenant_account_ref": "string",
  • "account_id": "string",
  • "static_token_id": "string",
  • "merchant_name": "string",
  • "transaction_amount": 0,
  • "transaction_currency": "string",
  • "creation_time": "2019-08-24T14:15:22Z"
}

Out of Band (OOB) challenge response

This API is used for you to update our system with the 3DS challenge response in case of the Out of Band (OOB) challenge flow.

See 3DS Out of Band (OOB) challenge flow for more details.

Request Body schema: application/json
required
three_ds_challenge_id
required
string

3DS Request ID in Open Fabric

static_token_id
required
string

Static token identifier in Open Fabric representing a Virtual Card

tenant_customer_ref
required
string

Customer identifier in your system

tenant_account_ref
required
string

Account identifier in your system

challenge_result
required
string (TenantThreeDsActionResult)
Enum: "approved" "declined"

Result of the 3DS challenge

reason
string

Required if challenge_result is declined

creation_time
required
string <date-time>

Creation time of the 3DS response in ISO 8601 format

Responses

Request samples

Content type
application/json
{
  • "three_ds_challenge_id": "string",
  • "static_token_id": "string",
  • "tenant_customer_ref": "string",
  • "tenant_account_ref": "string",
  • "challenge_result": "approved",
  • "reason": "string",
  • "creation_time": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "details": [
    ]
}

OutSend OTP request

This notification is sent to your backend when a 3D Secure challenge requires an OTP to be sent to the cardholder.

See 3DS OTP flow for more details.

Request Body schema: application/json
required
three_ds_challenge_id
required
string

3DS Request ID in Open Fabric

tenant_customer_ref
required
string

Customer identifier in your system

customer_id
required
string

Customer identifier in Open Fabric

tenant_account_ref
required
string

Account identifier in your system

account_id
required
string

Account identifier in Open Fabric

static_token_id
required
string

Static token identifier in Open Fabric representing a Virtual Card

merchant_name
required
string

Name of the merchant

transaction_amount
number

Amount of the transaction. If not present or 0, it is a non-payment 3DS authentication.

transaction_currency
string

Currency code for the transaction (e.g., USD, EUR). Not present for non-payment 3DS authentications.

creation_time
required
string <date-time>

Creation time of the 3DS request in ISO 8601 format

authentication_credential
string

The OTP sent to the customer

encrypted_authentication_credential
string

A JWE-encrypted string containing the OTP sent to the customer.

When pre-configured between yourself and Open Fabric, the OTP is delivered in encrypted form using an encryption key exchanged offline during onboarding.

Responses

Request samples

Content type
application/json
{
  • "three_ds_challenge_id": "string",
  • "tenant_customer_ref": "string",
  • "customer_id": "string",
  • "tenant_account_ref": "string",
  • "account_id": "string",
  • "static_token_id": "string",
  • "merchant_name": "string",
  • "transaction_amount": 0,
  • "transaction_currency": "string",
  • "creation_time": "2019-08-24T14:15:22Z",
  • "authentication_credential": "string",
  • "encrypted_authentication_credential": "string"
}

Response samples

Content type
application/json
{
  • "three_ds_challenge_id": "string",
  • "masked_email": "string",
  • "masked_phone_number": "string"
}

Clearing

Messages related to clearing. These are messages sent from our platform to your backend via notifications and reporting.

See Clearing operations for more details.

Clearing record

network_clearing_ref
required
string

A unique identifier for this clearing instruction received from the network

type
required
string (PbaClearingType)
Enum: "final_auth" "final_auth_reversal" "final_auth_partial" "final_auth_partial_reversal" "pre_auth_partial" "pre_auth_partial_reversal" "pre_auth_final" "pre_auth_final_reversal" "final_auth_expiry" "pre_auth_expiry" "refund" "refund_reversal" "refund_expiry" "chargeback_challenge" "chargeback_challenge_reversal" "chargeback" "chargeback_reversal" "fee_collection_credit" "fee_collection_credit_reversal" "fee_collection_debit" "fee_collection_debit_reversal" "unlinked_auth_partial" "unlinked_auth_final" "unlinked_auth_partial_reversal" "unlinked_auth_final_reversal" "unlinked_refund" "unlinked_refund_reversal" "unlinked_chargeback"

The type of clearing instruction

transfer_type
required
string (PbaTransferType)
Enum: "consumer_debit" "consumer_credit" "ahi_debit" "ahi_credit"

The direction of transfer deferred from type above.

  • consumer_debit means fund movement from the customer's financial account
  • consumer_credit means fund movement to the customer's financial account
  • ahi_debit means fund movement from your financial account
  • ahi_credit means fund movement to your financial account

Examples:

  • final_auth -> consumer_debit
  • final_auth_reversal -> consumer_credit
  • fee_collection_credit -> ahi_credit
  • fee_collection_credit_reversal -> ahi_debit
is_potential_chargeback
required
boolean

Indicator received from the network signaling that this clearing instruction may result in a chargeback (e.g. total clearing amount exceeds the original authorized amount). You should follow the instruction to clear the amount and may decide to initiate a chargeback for the additional amount at your discretion.

original_transaction_id
string

The transaction identifier of the original authorization in Open Fabric. Not present for all unlinked types and fee_collection. For Refund and Chargeback, this refers to the original final authorization or pre-authorization transaction that this refund is linked to.

transaction_id
string

Transaction identifier of this clearing instruction itself. Only populated when using the Ledger APIs.

network_transaction_ref
string

Transaction Reference received from the network

network_acquirer_transaction_ref
string

Acquirer Transaction Reference received from the network

original_tenant_transaction_ref
string

The original transaction identifier of the original authorization in your system. Not present for all unlinked types and fee_collection. For Refund and Chargeback, this refers to the original final authorization or pre-authorization transaction that this refund is linked to.

customer_id
string

Customer identifier in Open Fabric

tenant_account_ref
string

Account identifier in your system

tenant_customer_ref
string

Customer identifier in your system

network_merchant_name
required
string

Merchant name received from the network

network_merchant_outlet_address
required
string

Merchant outlet address received from the network

network_merchant_id
required
string

Merchant ID received from the network

amount
required
number

Transaction amount in major units

currency
required
string

Transaction currency code (ISO 4217)

billing_amount
required
number

Billing amount in major units

billing_currency_code
required
string

Billing currency code (ISO 4217)

billing_exchange_rate
required
number

Exchange rate when calculating billing amount

settlement_amount
required
number

Settlement amount in major units

settlement_currency_code
required
string

Settlement currency code (ISO 4217)

settlement_exchange_rate
required
number

Exchange rate when calculating settlement amount

interchange_fee_amount
required
number

Interchange fee amount in major units

interchange_fee_currency_code
required
string

Interchange fee currency code (ISO 4217)

network_clearing_file_ref
required
string

Reference ID for the clearing file (EOC report) received from the network

network_clearing_file_name
required
string

Name of the clearing file (EOC report) received from the network

network_clearing_timestamp
required
string

Timestamp of the clearing file (EOC report) received from the network

transaction_source
required
string (PbaTransactionSource)
Enum: "ecommerce" "terminal" "unsupported_dfle" "unsupported_tagc" "unsupported_brcd" "unsupported_mgst" "unsupported_unkw" "unsupported_mail" "unsupported_tlph" "unsupported_tvpy" "unsupported_mobl"

The source of the transaction:

  • ecommerce for ecommerce transactions
  • terminal for terminal transactions
network_posting_file_id
required
string

The network identifier of the file used for posting to the cardholder’s account in which the transaction appeared. For Mastercard, it is the identifier of the GCMS file.

network_merchant_category_code
string

Merchant category code received from the network

network_acquirer_id
required
string

Merchant acquirer ID received from the network

network_merchant_country_code
string

Country Code - ISO 3166 Alpha-2

is_converted_pre_auth
required
boolean

True indicates this is a final authorization converted from a pre-authorization

network_merchant_terminal_id
string

Merchant terminal ID received from the network

network_merchant_city
string

Merchant city received from the network

card_program_id
string

ID of the card program in which the transaction occurred

financial_account_id
string

Card program prefix + tenant account reference used in the transaction

{
  • "network_clearing_ref": "string",
  • "type": "final_auth",
  • "transfer_type": "consumer_debit",
  • "is_potential_chargeback": true,
  • "original_transaction_id": "string",
  • "transaction_id": "string",
  • "network_transaction_ref": "string",
  • "network_acquirer_transaction_ref": "string",
  • "original_tenant_transaction_ref": "string",
  • "customer_id": "string",
  • "tenant_account_ref": "string",
  • "tenant_customer_ref": "string",
  • "network_merchant_name": "string",
  • "network_merchant_outlet_address": "string",
  • "network_merchant_id": "string",
  • "amount": 0,
  • "currency": "string",
  • "billing_amount": 0,
  • "billing_currency_code": "string",
  • "billing_exchange_rate": 0,
  • "settlement_amount": 0,
  • "settlement_currency_code": "string",
  • "settlement_exchange_rate": 0,
  • "interchange_fee_amount": 0,
  • "interchange_fee_currency_code": "string",
  • "network_clearing_file_ref": "string",
  • "network_clearing_file_name": "string",
  • "network_clearing_timestamp": "string",
  • "transaction_source": "ecommerce",
  • "network_posting_file_id": "string",
  • "network_merchant_category_code": "string",
  • "network_acquirer_id": "string",
  • "network_merchant_country_code": "string",
  • "is_converted_pre_auth": true,
  • "network_merchant_terminal_id": "string",
  • "network_merchant_city": "string",
  • "card_program_id": "string",
  • "financial_account_id": "string"
}

OutClearing file ready notification

Notification sent when a clearing file is ready to be processed.

Request Body schema: application/json
required
notification_id
required
string <uuid>

The unique identifier for the notification

type
required
string
Value: "v1:pba:eoc:clearing_file_ready"
created_at
required
string <date-time>

The creation timestamp of the notification in ISO 8601 format

required
object (EOCFileProcessedNotification)

v1:pba:eoc:clearing_file_ready

Responses

Request samples

Content type
application/json
{
  • "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
  • "type": "v1:pba:eoc:clearing_file_ready",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Settlement

Messages related to settlement. These are messages sent from our platform to your backend via notifications and reporting.

See Settlement for more details.

Settlement Report

required
object (ReconciliationAndNetSettlementSummary)
required
Array of objects (SettlementRecordDetail)
{
  • "reconciliationAndNetSettlementSummary": {
    },
  • "settlementRecordDetails": [
    ]
}

OutSettlement file ready notification

Notification sent when a settlement file is ready to be processed.

Request Body schema: application/json
required
notification_id
required
string <uuid>

The unique identifier for the notification

type
required
string
Value: "v1:pba:eos:net_settlement_file_ready"
created_at
required
string <date-time>

The creation timestamp of the notification in ISO 8601 format

required
object (EOSNetSettlementNotification)

v1:pba:eos:net_settlement_file_ready

Responses

Request samples

Content type
application/json
{
  • "notification_id": "f96afe21-aef9-465c-a9f6-813055655b04",
  • "type": "v1:pba:eos:net_settlement_file_ready",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Manage Rulesets

APIs to create and manage spend control rulesets.

See Manage Rulesets for implementation guidance.

Create Ruleset

Creates a new ruleset with optional embedded rules. Rule names are auto-generated using pattern {template_code}_{counter}.

Request Body schema: application/json
required
name
required
string^[a-zA-Z0-9_-]+$

Ruleset name (alphanumeric with dash/underscore)

description
string

Ruleset description

is_active
boolean
Default: true

Active status

is_default
boolean
Default: false

Set as tenant default ruleset

effective_from
string <date-time>

Start date for effectiveness

effective_to
string <date-time>

End date for effectiveness

Array of objects (CreateRuleRequest)

List of rules to create

Responses

Request samples

Content type
application/json
Example
{
  • "name": "standard-account-limits",
  • "description": "Default spending limits",
  • "is_active": true,
  • "is_default": true,
  • "effective_from": "2026-03-17T03:45:40.745Z",
  • "effective_to": "2026-03-17T03:45:40.745Z",
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "is_active": true,
  • "is_default": true,
  • "effective_from": "2019-08-24T14:15:22Z",
  • "effective_to": "2019-08-24T14:15:22Z",
  • "rules": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List Rulesets

Lists all rulesets for the tenant with pagination support.

query Parameters
is_active
boolean

Filter by active status

page
integer
Default: 1

Page number

limit
integer <= 100
Default: 20

Results per page

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get Ruleset

Retrieves a specific ruleset by ID with all its rules.

path Parameters
ruleset_id
required
string <uuid>

Ruleset identifier (UUID)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "is_active": true,
  • "is_default": true,
  • "effective_from": "2019-08-24T14:15:22Z",
  • "effective_to": "2019-08-24T14:15:22Z",
  • "rules": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Ruleset

Updates ruleset metadata and manages rules. Rules can be added, updated, or removed in a single request.

path Parameters
ruleset_id
required
string <uuid>

Ruleset identifier (UUID)

Request Body schema: application/json
required
name
string^[a-zA-Z0-9_-]+$

Updated ruleset name

description
string

Updated description

is_active
boolean

Updated active status

is_default
boolean

Set as tenant default ruleset

effective_from
string <date-time>

Updated start date

effective_to
string <date-time>

Updated end date

object (RuleModifications)

Rule modifications for update request

Responses

Request samples

Content type
application/json
Example
{
  • "is_default": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "is_active": true,
  • "is_default": true,
  • "effective_from": "2019-08-24T14:15:22Z",
  • "effective_to": "2019-08-24T14:15:22Z",
  • "rules": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Ruleset

Deletes a ruleset by ID.

path Parameters
ruleset_id
required
string <uuid>

Ruleset identifier (UUID)

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "details": [
    ]
}

Ruleset Assignment

APIs to assign spend control rulesets to accounts and tokens.

See Ruleset Assignment for implementation guidance.

Assign Ruleset to Account

Assigns a ruleset to a customer account with a specific scope definition.

path Parameters
account_id
required
string <uuid>

Account identifier in Open Fabric

Request Body schema: application/json
required
ruleset_id
required
string <uuid>

Ruleset identifier

required
object (RulesetScope)

Scope definition for ruleset assignment

Responses

Request samples

Content type
application/json
{
  • "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773",
  • "scope": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
  • "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773",
  • "scope": {
    },
  • "created_at": "2019-08-24T14:15:22Z"
}

List Account Ruleset Assignments

Lists all rulesets assigned to an account.

path Parameters
account_id
required
string <uuid>

Account identifier in Open Fabric

query Parameters
level
string (AuthPolicyRulesetScopeLevel)
Enum: "account" "token"

Filter by scope level

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update Ruleset Assignment

Updates an existing ruleset assignment for an account.

path Parameters
account_id
required
string <uuid>

Account identifier in Open Fabric

assignment_id
required
string <uuid>

Assignment identifier

Request Body schema: application/json
required
ruleset_id
required
string <uuid>

Ruleset identifier

required
object (RulesetScope)

Scope definition for ruleset assignment

Responses

Request samples

Content type
application/json
{
  • "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773",
  • "scope": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
  • "ruleset_id": "ca688a19-2766-4b2c-aefa-28d16a464773",
  • "scope": {
    },
  • "created_at": "2019-08-24T14:15:22Z"
}

Remove Ruleset Assignment

Removes a ruleset assignment from an account.

path Parameters
account_id
required
string <uuid>

Account identifier in Open Fabric

assignment_id
required
string <uuid>

Assignment identifier

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "details": [
    ]
}

Transaction orchestration

APIs you use to approve/decline and query transactions during online orchestration.

See Orchestrated integration guide for the end-to-end flow.

OutTransaction request

Open Fabric calls your backend to create a transaction request after a customer selects your payment method at checkout.

You return a response containing a redirect_url to your approval flow and gateway URLs used to redirect the customer back to checkout.

Request Body schema: application/json
required
One of
tenant_partner_id
required
string

Reference ID to identify Partner on Tenant system

fabric_reference_id
required
string

OpenFabric Generated ID for this Transaction - UUID

partner_reference_id
required
string

Transaction ID set by Partner and sent to OpenFabric

tenant_id
required
string <uuid>

OpenFabric Generated ID for your Tenant account - UUID

gateway_success_url
required
string <uri>

This is the URL Tenant should redirect customers to when the transaction is successfully approved by Tenant

gateway_fail_url
required
string <uri>

This is the URL Tenant should redirect Customers to when the transaction is declined by Tenant. The transaction could be declined, because the customer cancelled the transaction on Tenant's payment flow or the Tenant simply declined to approve this transaction

object (CustomerInfo)

OpenFabric collects the below customer Info Collection from merchants. We will pass-through the collected info to Tenant

amount
required
number

Transaction amount for which Tenant's authorization is requested

currency
required
string = 3 characters ^[A-Z]*$

Transaction Currency for which Tenant's authorization is requested (ISO 4217 Alpha-3 currency codes)

required
object (TransactionDetails)

Transaction Details sent by Partner.

object (PatLinkInfo)
partner_name
string

Partner name

source
string

Source of transaction request

Responses

Request samples

Content type
application/json
{
  • "tenant_partner_id": "27666828-57f9-4709-a9a9-84167e091f5f",
  • "fabric_reference_id": "ff0398e5-d045-441f-b130-bcd517964775",
  • "partner_reference_id": "P1293201980299030",
  • "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
  • "gateway_success_url": "https://gateway.dev.openfabric.co",
  • "gateway_fail_url": "https://gateway.dev.openfabric.co",
  • "customer_info": {
    },
  • "amount": 120.1,
  • "currency": "SGD",
  • "transaction_details": {
    },
  • "pat_link": {
    },
  • "partner_name": "string",
  • "source": "string"
}

Response samples

Content type
application/json
{}

Approve / Decline a transaction

Tenant can call this API to approve or fail a transaction.

Request Body schema: application/json
required

Open Fabric will create a Transaction with the default state created. Tenant can update the transaction to approved or failed.

tenant_reference_id
required
string >= 4 characters ^[a-zA-Z0-9\-_@\.]*$

Transaction ID in Tenant system. This is the same transaction ID that Tenant shared as part of the above step

status
required
string (TransactionApprovalStatus)
Enum: "approved" "failed"

Tenant can either Approve or Fail a transaction. In case of Failed, reason is mandatory.

approved_amount
number

Approved transaction amount

approved_currency
string = 3 characters ^[A-Z]*$

Approved transaction Currency (ISO 4217 Alpha-3 currency codes)

reason
string

Responses

Request samples

Content type
application/json
Example
{
  • "tenant_reference_id": "cd992711-498f-47be-b636-cf2e3eaad935",
  • "status": "approved"
}

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "details": [
    ]
}

Get a transaction data

This API can be used to fetch a transaction

path Parameters
id
required
string <uuid>

OpenFabric Generated ID for this Transaction. You will receive this part of Update Transaction Response.

Responses

Response samples

Content type
application/json
{}

Get a transaction detailed data

This API can be used to fetch transaction with all details including card, customer and transaction information submitted by Partner.

path Parameters
id
required
string <uuid>

OpenFabric Generated ID for this Transaction. You will receive this part of Update Transaction Response.

Responses

Response samples

Content type
application/json
{
  • "id": "ff0398e5-d045-441f-b130-bcd517964775",
  • "partner_reference_id": "P1293201980299030",
  • "tenant_reference_id": "Tenant-cd992711-498f-47be-b636-cf2e3eaad935",
  • "tenant_partner_id": "27666828-57f9-4709-a9a9-84167e091f5f",
  • "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
  • "partner_id": "9bde4fbf-893b-49f9-b7b3-4079a76bb362",
  • "partner_name": "Lazada",
  • "partner_redirect_success_url": "http://sample-merchant-flow.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=PAID",
  • "partner_redirect_fail_url": "http://sample-merchant-flow.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=CANCELLED",
  • "gateway_fail_url": "http://of-gateway",
  • "gateway_success_url": "http://of-gateway.s3-website-ap-southeast-1.amazonaws.com?reference_id=P1293201980299030&state=PAID",
  • "payment_redirect_web_url": "http://sample-bnpl-web.openfabric.co",
  • "card": {
    },
  • "customer_id": "88db7aa7-2cdd-42cc-9827-8d46f936ef79",
  • "customer_info": {
    },
  • "amount": 120.1,
  • "currency": "SGD",
  • "status": "failed",
  • "card_reference_id": "7743087",
  • "created_at": "2021-11-06T04:26:47.450Z",
  • "updated_at": "2021-11-06T04:26:47.450Z",
  • "transaction_details": {
    }
}

OutTransaction charged update

Callback sent to your backend after a one-time payment credential is charged successfully.

Request Body schema: application/json
required
Array
notification_id
string <uuid>

ID of the notification

type
required
string
Value: "transaction:charged"

type of notification

created_at
required
string <date-time>
required
object (schemas-AccountTransactionChargedNotification)

Notification for transaction charge

Responses

Request samples

Content type
application/json
[
  • {
    }
]

OutTransaction reversed update

Callback sent to your backend when a reversal or refund is issued against a one-time payment credential.

Request Body schema: application/json
required
Array
notification_id
string <uuid>

ID of the notification

type
required
string
Value: "transaction:reversed"

type of notification

created_at
required
string <date-time>
required
object (schemas-AccountTransactionReversedNotification)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

OutTransaction credited update

Callback sent to your backend when a transaction is credited.

Request Body schema: application/json
required
Array
notification_id
string <uuid>

ID of the notification

type
required
string
Value: "transaction:credited"

type of notification

created_at
required
string <date-time>
required
object (schemas-AccountTransactionCreditedNotification)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Callback subscriptions

APIs to manage your callback (webhook) subscriptions for online-orchestration updates.

List all webhook subscriptions

List all webhook subscriptions for Tenant

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Create a webhook subscription

Create a webhook subscription for Tenant

query Parameters
webhook_type
string (WebhookType)
Enum: "online" "pat_provision"

Webhook type

Request Body schema: application/json
required

Notification subscription object to init

config
required
object

Configuration options for the subscription

subscribed_events
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "type": "webhook",
  • "subscribed_events": [
    ],
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "cd992711-498f-47be-b636-cf2e3eaad935",
  • "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
  • "type": "webhook",
  • "subscribed_events": [
    ],
  • "config": {
    }
}

Update a subscription

Update an existing webhook subscription for Tenant

path Parameters
id
required
string <uuid>

ID of an existing notification subscription

query Parameters
webhook_type
string (WebhookType)
Enum: "online" "pat_provision"

Webhook type

Request Body schema: application/json
required

Notification subscription object to update

config
required
object

Configuration options for the subscription

subscribed_events
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "type": "webhook",
  • "subscribed_events": [
    ],
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "cd992711-498f-47be-b636-cf2e3eaad935",
  • "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
  • "type": "webhook",
  • "subscribed_events": [
    ],
  • "config": {
    }
}

Partner management

APIs to create, update, list, and deactivate merchants/payment gateways (“partners”) that integrate with Open Fabric.

See Partner onboarding and management APIs.

List all Partners

Get all Partners associated with current Tenant

query Parameters
sort
string
Example: sort=name,+tenant_partner_id

Multiple sorting conditions

name
string

Filter by name

tenant_partner_id
string

Filter by Tenant Partner id

slug
string

Filter by slug

country
string

Filter by country

website_url
string

Filter by website

category
string

Filter by category

page
integer

Current page

limit
integer
Deprecated

Number of records

page_size
integer

Number of records

labels
string
Example: labels=labels=qrph,nfc

Filter by Labels

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metadata": {
    }
}

Create a Partner

Create a Partner

Request Body schema: application/json
name
required
string
tenant_partner_id
required
string [ 4 .. 36 ] characters ^[a-zA-Z0-9\-_@\.]*$
slug
required
string [ 4 .. 30 ] characters ^[a-z0-9][a-z0-9\-]*[a-z0-9]$
email
string <email>
website_url
required
string <uri>
category
string
country
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tenant_partner_id": "string",
  • "slug": "string",
  • "email": "user@example.com",
  • "website_url": "http://example.com",
  • "category": "string",
  • "country": "string"
}

Response samples

Content type
application/json
{
  • "id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
  • "name": "Lazada",
  • "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
  • "slug": "lazada",
  • "website_url": "https://www.lazada.co.th/"
}

Get a Partner details

Get a Partner details

path Parameters
partner_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
  • "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
  • "name": "Lazada",
  • "slug": "lazada",
  • "website_url": "https://www.lazada.co.th/",
  • "email": "admin@lazada.co.th"
}

Update a Partner

Update a Partner with the current Tenant

path Parameters
partner_id
required
string
Request Body schema: application/json
required

Body request to update Partner for Tenant

name
string
website_url
string <uri>
category
string
country
string
email
string <email>
tenant_partner_id
string [ 4 .. 36 ] characters ^[a-zA-Z0-9\-_@\.]*$

Responses

Request samples

Content type
application/json
{
  • "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
  • "name": "Lazada",
  • "website_url": "https://www.lazada.co.th/",
  • "email": "admin@lazada.co.th"
}

Response samples

Content type
application/json
{
  • "id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
  • "tenant_partner_id": "4fde45e1-6e4f-4039-a8de-bb316a4adeb8",
  • "name": "Lazada",
  • "slug": "lazada",
  • "website_url": "https://www.lazada.co.th/",
  • "email": "admin@lazada.co.th"
}

Deactivate a Partner

Delete Partner association with the current Tenant

path Parameters
partner_id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "ok"
}

Partner settings

APIs to manage partner credentials, callback subscriptions, and payment gateway credentials used for token handover.

See Partner onboarding and management APIs.

Credential: Retrieve API credentials

Retrieve API credentials of a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

alias
required
string^[\S]+$

Alias for the credentials

Responses

Response samples

Content type
application/json
{
  • "alias": "default",
  • "client_id": "id119i9d8ekasjc9x",
  • "client_secret": "secret3jjsj3jdjk2jkesk"
}

Credential: Renew API credentials

Revoke and request new API credentials of a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

alias
required
string^[\S]+$

Alias for the credentials

Responses

Response samples

Content type
application/json
{
  • "alias": "default",
  • "client_id": "id119i9d8ekasjc9x",
  • "client_secret": "secret3jjsj3jdjk2jkesk"
}

Webhook: Create a webhook subscription

Create a webhook subscription for a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

query Parameters
webhook_type
string (WebhookType)
Enum: "online" "pat_provision"

Webhook type

Request Body schema: application/json
required

Notification subscription object to init

config
required
object

Configuration options for the subscription

subscribed_events
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "type": "webhook",
  • "subscribed_events": [
    ],
  • "config": {}
}

Response samples

Content type
application/json
{
  • "id": "cd992711-498f-47be-b636-cf2e3eaad935",
  • "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
  • "partner_id": "00fcf093-71fb-4349-8c0b-de810480d6b2",
  • "type": "webhook",
  • "subscribed_events": [
    ],
  • "config": {}
}

Webhook: Update a subscription

Update a webhook subscription of a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

id
required
string <uuid>

ID of an existing notification subscription

query Parameters
webhook_type
string (WebhookType)
Enum: "online" "pat_provision"

Webhook type

Request Body schema: application/json
required

Notification subscription object to update

config
required
object

Configuration options for the subscription

subscribed_events
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "type": "webhook",
  • "subscribed_events": [
    ],
  • "config": {}
}

Response samples

Content type
application/json
{
  • "id": "cd992711-498f-47be-b636-cf2e3eaad935",
  • "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
  • "partner_id": "00fcf093-71fb-4349-8c0b-de810480d6b2",
  • "type": "webhook",
  • "subscribed_events": [
    ],
  • "config": {}
}

PG: List all PG credentials

List all PG credentials of a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

query Parameters
pg_name
string^[\S]+$

pg name

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

PG: Create/Update credentials for a PG

Update a PG credential for a PG of a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

pg_name
required
string^[\S]+$

PG name

Request Body schema: application/json
required
credential_format
required
string (CredentialFormat)
Value: "api_key_pair"
ApiKeyPGCredential (object) (PGCredentialData)
object
object (ChargeConfig)

Responses

Request samples

Content type
application/json
{
  • "value": {
    }
}

Response samples

Content type
application/json
{
  • "id": "143334c3-1b7d-433a-939a-f63c9022f800",
  • "tenant_id": "a6dbbdab-1b7d-433a-939a-f63c9022f833",
  • "partner_id": "27666828-57f9-4709-a9a9-84167e091f5f",
  • "pg_name": "xendit",
  • "credential_format": "api_key_pair",
  • "redacted_credentials": {
    },
  • "additional_params": {
    },
  • "charge_config": {
    }
}

PG: Get credentials for a PG

Get a PG credential for a PG of Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

pg_name
required
string^[\S]+$

PG name

Responses

Response samples

Content type
application/json
{
  • "id": "143334c3-1b7d-433a-939a-f63c9022f800",
  • "tenant_id": "a6dbbdab-1b7d-433a-939a-f63c9022f833",
  • "partner_id": "27666828-57f9-4709-a9a9-84167e091f5f",
  • "pg_name": "xendit",
  • "credential_format": "api_key_pair",
  • "redacted_credentials": {
    },
  • "additional_params": {
    },
  • "charge_config": {
    }
}

PG: Delete credentials for a PG

Delete credentials for a PG of a Partner

path Parameters
partner_id
required
string <uuid>

Partner ID

pg_name
required
string^[\S]+$

PG name

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "details": [
    ]
}

Get configurations metadata for PG

Get configuration metadata for PG

Responses

Response samples

Content type
application/json
{ }

Merchant / gateway orchestration

APIs that merchants and payment gateways use with the Open Fabric Merchant SDK to create and manage transactions.

See Merchant / gateway integration guides.

Create a transaction

This will be called by Partner to initialize a transaction before interacting with payment methods

query Parameters
txn_trace_id
string <uuid>

Trace UUID (v4) to follow payment sessions

header Parameters
Idempotency-Key
string

Unique value submitted by the client to ensure idempotent request when creating transaction.

Request Body schema: application/json
required

Transaction object to init

instrument
string
Default: "web_checkout"

Instrument of the transaction request. Can be omitted for the web_checkout transaction request.

tenant_id
string <uuid>

OpenFabric Generated ID for the Tenant of the payment method, only for backward-compatibility. If not provided, it will use the ID of the Tenant linked with Partner.

partner_redirect_success_url
required
string <uri>

Redirect URL Configured by Partner - when transaction is approved by Tenant

partner_redirect_fail_url
required
string <uri>

Redirect URL Configured by Partner - when transaction is denied by Tenant

partner_reference_id
required
string^[a-zA-Z0-9\-_@\.]*$

Transaction ID set by Partner and sent to OpenFabric

required
object (CustomerInfo)

OpenFabric collects the below customer Info Collection from merchants. We will pass-through the collected info to Tenant

amount
required
number >= 0.01

Transaction amount for which Tenant's authorization is requested

currency
required
string = 3 characters ^[A-Z]*$

Transaction Currency for which Tenant's authorization is requested (ISO 4217 Alpha-3 currency codes)

required
object (TransactionDetails)

Transaction Details sent by Partner.

pg_name
string

Payment Gateway name

pg_publishable_key
string

Payment Gateway's publishable_key

pg_flow
string (PGFlow)
Enum: "tokenization" "charge"

for which flow that Partner would like OF to execute. If it is not set, default to Tokenization

pg_additional_params
object

Additional parameters required in the card tokenization/charge request for the given Payment Gateway

Responses

Request samples

Content type
application/json
{
  • "partner_reference_id": "P1293201980299030",
  • "tenant_id": "00fcf093-71fb-4349-8c0b-de810480d6b1",
  • "partner_redirect_success_url": "https://sample-merchant-flow.dev.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=PAID",
  • "partner_redirect_fail_url": "https://sample-merchant-flow.dev.openfabric.co?id=f0398e5-d045-441f-b130-bcd517964775&state=CANCELLED",
  • "customer_info": {
    },
  • "amount": 120.1,
  • "currency": "SGD",
  • "transaction_details": {
    }
}

Response samples

Content type
application/json
{}

Get transaction details

This will return Detailed Transaction by Open Fabric Reference ID

path Parameters
id
required
string <uuid>
query Parameters
txn_trace_id
string <uuid>

Trace UUID (v4) to follow payment sessions

Responses

Response samples

Content type
application/json
{}

Refund a transaction

This will refund a transaction that was charged by Open Fabric on behalf of Partner

path Parameters
id
required
string <uuid>
header Parameters
Idempotency-Key
string

Unique value submitted by the partner to ensure idempotent request when refunding transaction.

Request Body schema: application/json
required

Refund request body

amount
required
number >= 0.001

Refund amount

additional_properties
object
reason
string

Responses

Request samples

Content type
application/json
{
  • "amount": 10.1,
  • "reason": "Out of goods"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get transaction by partner reference id

This will fetch the transaction by partner reference id

query Parameters
partner_reference_id
required
string

Responses

Response samples

Content type
application/json
{}

Get payment method metadata

With the payment methods input, we identify Partner by access_token, only payment methods available with this Partner will be returned

query Parameters
txn_trace_id
string <uuid>

Trace UUID (v4) to follow payment sessions

Responses

Response samples

Content type
application/json
{
  • "value": [
    ]
}

OutTransaction approved notification

Notification sent to your partner's backend when a transaction is approved.

Request Body schema: application/json
required
txn_id
required
string <uuid>

OpenFabric Transaction ID

txn_ref_id
required
string <uuid>

Transaction reference ID. Internally it is the equivalent of partner_reference_id

txn_state
required
string (MerchantTransactionStatus)
Enum: "in_progress" "approved" "failed" "reversed"

Transaction status for Partner

txn_amt
required
number

Transaction amount

txn_ccy
required
string

Transaction currency

txn_app_amt
required
number

Transaction approved amount

txn_app_ccy
required
string

Transaction approved currency

txn_created_at
required
string <date-time>
txn_updated_at
required
string <date-time>
txn_tenant_id
string
txn_card_token
string

Short-lived token to access the VCN details generated for the transaction. Internally it is the equivalent of card_fetch_token

txn_pg
string

Payment gateway name. Used for PG integrated flow

txn_pg_token
string

Payment gateway token. Used for PG integrated flow

txn_pg_charge_id
string

id of the charge transaction sent back from pg

txn_pg_response
object

Responses

Request samples

Content type
application/json
{
  • "txn_id": "ff0398e5-d045-441f-b130-bcd517964775",
  • "txn_ref_id": "P1293201980299030",
  • "txn_state": "approved",
  • "txn_amt": 120.1,
  • "txn_ccy": "SGD",
  • "txn_app_amt": 120.1,
  • "txn_app_ccy": "SGD",
  • "txn_created_at": "2021-11-06T04:26:47.450Z",
  • "txn_updated_at": "2021-11-06T04:26:47.450Z",
  • "txn_pg": "stripe",
  • "txn_pg_token": "YTZkYmJkYWItMWI3ZC00MzNhLTkzOWEtZjYzYzkwMjJmODMz"
}

OutTransaction failed notification

Notification sent to your partner's backend when a transaction is failed.

Request Body schema: application/json
required
txn_id
required
string <uuid>

OpenFabric Transaction ID

txn_ref_id
required
string <uuid>

Transaction reference ID. Internally it is the equivalent of partner_reference_id

txn_state
required
string (MerchantTransactionStatus)
Enum: "in_progress" "approved" "failed" "reversed"

Transaction status for Partner

txn_created_at
required
string <date-time>
txn_updated_at
required
string <date-time>
txn_tenant_id
string
txn_reason
string

Reason to decline the transaction, submitted by Tenant.

Responses

Request samples

Content type
application/json
{
  • "txn_id": "ff0398e5-d045-441f-b130-bcd517964775",
  • "txn_ref_id": "P1293201980299030",
  • "txn_state": "failed",
  • "txn_created_at": "2021-11-06T04:26:47.450Z",
  • "txn_updated_at": "2021-11-06T04:26:47.450Z",
  • "txn_reason": "Insufficient amount"
}

Merchant / gateway settings

APIs that merchants and payment gateways use to manage their integration settings.

See Merchant / gateway integration guides.

Update settings

Update webhook subscription and PG credentials settings of a Partner

Request Body schema: application/json
required

Webhook and PG credentials details request for Partner

object (AccountNotificationSubscriptionRequest)
object

Responses

Request samples

Content type
application/json
{
  • "value": {
    }
}

Response samples

Content type
application/json
{
  • "webhook": {
    },
  • "payment_gateway": {
    }
}