Unscheduled Card-on-File Payments (UCOF)

Unscheduled Card-on-File (UCOF) Payments allow merchants to process future payments using payment credentials previously authorized by the customer during an initial Cardholder-Initiated Transaction (CIT).

UCOF Payments are designed for scenarios where future charges cannot be scheduled in advance and are triggered by a business event defined by the merchant. Typical examples include delayed charges, additional service fees, no-show fees, usage-based billing, or incremental charges.

During the initial CIT, the merchant establishes the Merchant-Initiated Transaction (MIT) agreement by configuring the UCOF parameters. After the initial payment is successfully completed, future charges can be processed as Merchant-Initiated Transactions (MITs), using the stored payment credentials and the original CIT transaction reference.

Unlike Recurring Payments, UCOF does not support recurring schedules. The merchant is responsible for initiating each subsequent MIT whenever a valid business event occurs.

When to use UCOF

Use UCOF when the merchant charges a stored card without a predefined schedule, triggered by operational events such as:

Delayed charges
Hotel no-show fees
Additional hotel or rental charges
Usage-based billing
Pay-per-use services
Post-purchase adjustments
Incremental authorizations or additional service fees

How it Works

UCOF Payments are implemented in three steps.

Step 1 – Initial Cardholder-Initiated Transaction (CIT)
Step 2 – Subsequent Merchant-Initiated Transactions (MIT)
Step 3 – Receive Payment Notifications (Optional)

Step 1 – Initial Cardholder-Initiated Transaction (CIT)

The customer performs the initial payment.

During this transaction, the merchant establishes the Merchant-Initiated Transaction (MIT) agreement by configuring the required UCOF parameters.

Once the payment is successfully completed, SIBS Gateway generates an original-tx-id, which uniquely identifies the stored credential agreement and must be referenced whenever future UCOF Merchant-Initiated Transactions are submitted.

This step consists of the following actions:

Action 1 – Create the Order
Action 2 – Process the Payment
Action 3 – Get Transaction Status (Optional)

Action 1 – Create the Order

Start by creating a standard payment order using the Checkout Payment API.

For the complete request structure, required headers and standard payment fields, refer to the Create Order section of the API Integration documentation.

When creating the initial CIT, include the UCOF configuration fields described below. These fields establish the stored credential agreement that will be referenced by future Merchant-Initiated Transactions.

Endpoint URL

API	Operation
Checkout Payment API	POST /api/{version-id}/payments

UCOF Configuration Fields

Field	Type	Condition	Description	Example
`Request Body.merchantInitiatedTransaction`	MITTypeCode	Optional	Defines the Merchant-Initiated Transaction type. For UCOF payments, set this field to UCOF. Possible values: RCRR, UCOF.	“UCOF”
`Request Body.recurringTransaction`	RecurringTransaction	Conditional	Object that defines the Merchant-Initiated Transaction agreement. Required when merchantInitiatedTransaction is set to UCOF. For UCOF, only the amountQualifier field must be provided.	{…}
`Request Body.recurringTransaction.validityDate`	isoDateTime	Optional	Date until which the Merchant-Initiated Transaction agreement remains valid.	“2027-12-31T23:59:59Z”
`Request Body.recurringTransaction.amountQualifier`	String	Mandatory for UCOF	Qualifies the amount associated with the Merchant-Initiated Transaction. Possible values are ACTUAL, ESTIMATED and DEFAULT. For UCOF payments, this field must always be set to ESTIMATED.	“ESTIMATED”
`Request Body.recurringTransaction.amountQualifier`	String	Optional	Description of the Merchant-Initiated Transaction agreement.

Important

When configuring UCOF Payments, the transaction.paymentMethod must contain only the value “CARD”.

Example Request

Run in Postman

</> JSON 
{ 
    "merchant": { 
        "terminalId": {{TerminalID}}, 
        "channel": "web", 
        "merchantTransactionId": "{{merchantTrxID}}", 
        "websiteAddress": "https://website.com" 
    }, 
    "customer": { 
        "customerInfo": { 
            "customerLanguage": "pl" 
        } 
    }, 
    "transaction": { 
        "transactionTimestamp": "{{trxDatetime}}", 
        "description": "Transaction for order number {{trxOrderNum}} terminalId {{TerminalID}}", 
        "moto": false, 
        "paymentType": "AUTH", 
        "amount": { 
            "value": 50.50, 
            "currency": "PLN" 
        }, 
        "paymentMethod": [ 
            "CARD" 
        ] 
    }, 
    "tokenisation": { 
        "tokenisationRequest": { 
            "tokeniseCard": false 
        }, 
        "paymentTokens": [] 
    }, 
    "merchantInitiatedTransaction": "UCOF", 
    "recurringTransaction": { 
        "validityDate": "{{trxRecurrValidityDatetime}}", 
        "amountQualifier": "ESTIMATED", 
        "description": "UCOF transaction -> Order {{trxOrderNum}}" 
    } 
}

Action 2 – Process the Payment

Once the order has been created, complete the customer payment using the Card Purchase API.

Unlike the Checkout request, this operation does not use the Bearer Token in the Authorization header. Instead, the request must include the transactionSignature returned in the Checkout response.

The transactionSignature authorizes the payment execution for the transaction previously created through the Checkout API.

Endpoint URL

API	Operation
Card Purchase API	POST /api/{version-id}/payments/{transactionID}/card/purchase

Header Parameters

Field	Type	Required	Description	Example
`Content-Type`	string	Mandatory	Defines the content type of the request.	application/json
`Authorization`	string	Mandatory	Use `transactionSignature` returned by the Checkout API. This request must use the Digest authentication scheme.	Digest {transactionSignature}
`x-ibm-client-id`	string	Mandatory	Token identifying the client organization, provided during onboarding.	123456789

Example Purchase Request:

</> JSON 
{ 
    "cardInfo": { 
        "PAN": "5204740000001002", 
        "secureCode": "100", 
        "validationDate": "2025-12-31T00:00:00.000Z", 
        "cardholderName": "Jane Smith", 
        "createToken": false 
    } 
}

Run in Postman

Response

A successful technical response returns:

HTTP Status 200
returnStatus.statusCode = “000”

The paymentStatus indicates the outcome of the payment authorization.

Payment Status	Description
Success	The payment was successfully authorized and the recurring agreement was established.
Declined	The payment was declined. No recurring agreement is created.
Pending	The final payment result is not yet available. Use the Status API until a final status is returned.
Partial	Additional customer interaction is required (for example, 3DS authentication). The `actionResponse` element is provided for instructions on how to proceed.

The API response also includes the recurringTransaction.status field, which indicates whether the recurring configuration was successfully established during the initial payment. Only when this status is successful can the transaction be used as the reference for future UCOF Merchant-Initiated Transactions (MIT).

Action 3 – Get Transaction Status (Optional)

After the payment has been submitted, you can verify its processing status using the Status API.

Unlike the Card Purchase request, the Status API uses the same authentication method as the initial Checkout request. The Authorization header must contain the Bearer Token.

Endpoint URL

API	Operation
Payment Status API	GET /api/{version-id}/payments/{transactionID}/status

Header Parameters

Field	Type	Required	Description	Example
`Content-Type`	string	Mandatory	Defines the content type of the request.	application/json
`Authorization`	string	Mandatory	Bearer Token obtained through the authentication process.	Bearer xxxxxxxx
`x-ibm-client-id`	string	Mandatory	Token identifying the client organization, provided during onboarding.	123456789

Example Request

Run in Postman

Checkout Status Response

A successful technical response returns HTTP 200 with returnStatus.statusCode = “000”.

Use this operation whenever you need to retrieve the latest processing status of the transaction.

For a complete list of transaction status codes, error codes and decline reasons, refer to the Error Handling & Decline Codes documentation.

Step 2 – Process Subsequent UCOF Payments (MIT)

Once the initial payment has been successfully completed, the merchant can initiate Merchant-Initiated Transactions (MITs) whenever a valid business event occurs.

Each subsequent UCOF payment references the original-tx-id generated during the initial CIT and uses the payment credentials previously authorized by the customer.

Unlike Recurring Payments, UCOF transactions are not scheduled. Each MIT request must be explicitly submitted by the merchant.

This step consists of the following actions:

Action 1 – Submit the MIT Request (linkar com o titulo em questão da própria página)
Action 2 – Get Transaction Status (Optional) (linkar com o titulo em questão da própria página)

Action 1 – Submit the MIT Request

When UCOF payments are merchant-triggered, submit a Merchant-Initiated Transaction using the original-tx-id generated during the initial CIT.

The original-tx-id identifies the recurring agreement and links each MIT to the original customer-authorized transaction.

Endpoint

API	Operation
MIT API	POST /api/{version-id}/payments/{original-tx-id}/mit

Header Parameters

Field	Type	Required	Description	Example
`Content-Type`	string	Mandatory	Defines the content type of the request.	application/json
`Authorization`	string	Mandatory	Bearer Token obtained through the authentication process.	Bearer xxxxxxxx
`x-ibm-client-id`	string	Mandatory	Token identifying the client organization, provided during onboarding.	123456789

MIT Request Fields

Field	Type	Condition	Description
`original-tx-id (Path)`	String (Max36Text)	Mandatory	Original transaction identifier generated during the initial CIT. This value identifies the stored credential agreement used to process the Merchant-Initiated Transaction.
`transaction.transactionType`	String (Transaction Type Code)	Mandatory	Defines the Merchant-Initiated Transaction(MIT) type. Possible values: RCRR or UCOF.
`transaction.amount.value`	Number (double)	Mandatory	Amount to be charged.
`transaction.amount.currency`	String (Currency Code – ISO Alpha-3)	Mandatory	Currency used in the transaction.
`transaction.description`	String	Optional	Short description of the Merchant-Initiated Transaction.

Example Request

</> JSON 

{ 
    "merchant": { 
        "terminalId": "{{TerminalID}}", 
        "channel": "web", 
        "merchantTransactionId": "{{merchantTrxID}}" 
    }, 
    "transaction": { 
        "transactionTimestamp": "{{trxDatetime}}", 
        "transactionType": "UCOF", 
        "description": "Transaction for order {{trxOrderNum}}", 
        "amount": { 
            "value": 50.50, 
            "currency": "PLN" 
        }, 
        "originalTransaction": { 
            "id": "{{ originalTxId}}", 
            "datetime": "{{trxOriginalDatetime}}" 
        } 
    } 
}

Run in Postman

Action 2 – Get Transaction Status (Optional but Recommended)

After the Merchant-Initiated Transaction (MIT) has been submitted, you can verify its processing status using the Status API.

The Status API allows you to retrieve the latest processing status of the transaction whenever an immediate confirmation is not available or when you need to confirm the final payment result.

Unlike the Purchase API, this request uses the same authentication method as the initial Checkout request. The Authorization header must contain the Bearer Token.

Endpoint URL

API	Operation
Payment Status API	GET /api/{version-id}/payments/{transactionID}/status

Header Parameters

Field	Type	Required	Description	Example
`Content-Type`	string	Mandatory	Defines the content type of the request.	application/json
`Authorization`	string	Mandatory	Bearer Token obtained through the authentication process.	Bearer xxxxxxxx
`x-ibm-client-id`	string	Mandatory	Token identifying the client organization, provided during onboarding.	123456789

Example Request

Run in Postman

Response

A successful technical response returns:

HTTP Status 200

returnStatus.statusCode = “000”

Use this operation whenever you need to retrieve the latest processing status of the Merchant-Initiated Transaction.

For a complete list of transaction status codes, error codes and decline reasons, refer to the Error Handling & Decline Codes documentation.

Step 3 – Receive Payment Notifications (Optional)

To further automate your integration, you can configure Webhooks to receive asynchronous notifications whenever the status of a Merchant-Initiated Transaction changes.

When Webhooks are enabled, SIBS Gateway automatically sends event notifications to the merchant’s configured endpoint after each UCOF payment is processed. This allows your system to react to payment events in real time.

Typical notifications include:

Payment successfully processed
Payment declined
Payment pending
Payment processing completed

Webhooks complement the payment integration by providing an event-driven mechanism for receiving transaction updates, making it easier to keep your systems synchronized with the latest payment status.

For information about configuring Webhooks, supported events and implementation details, refer to the Webhooks Integration documentation.

Learn more about Webhooks here.

Unscheduled Card-on-File Payments (UCOF)

When to use UCOF

How it Works

Step 1 – Initial Cardholder-Initiated Transaction (CIT)

Action 1 – Create the Order

Endpoint URL

UCOF Configuration Fields

Example Request

Action 2 – Process the Payment

Endpoint URL

Header Parameters

Example Purchase Request:

Action 3 – Get Transaction Status (Optional)

Endpoint URL

Header Parameters

Example Request

Checkout Status Response

Step 2 – Process Subsequent UCOF Payments (MIT)

Action 1 – Submit the MIT Request

Endpoint

Header Parameters

MIT Request Fields

Example Request

Action 2 – Get Transaction Status (Optional but Recommended)

Endpoint URL

Header Parameters

Example Request

Response

Step 3 – Receive Payment Notifications (Optional)

On this page: