Partner Connect API

The Partner Connect API enables merchants and service providers to integrate with UTGL’s card services for securely binding customer payment cards and processing transactions. This API is designed for e-commerce platforms, payment gateways, and other merchant applications that need to accept payments from UTGL cardholders.

---

​

Overview

The Partner Connect API provides two main capabilities:

1. Card Binding - Securely link customer payment cards to your merchant system
2. Transaction Processing - Authorize, capture, void, and refund payments using bound cards

---

​

Architecture & Authentication

The Partner Connect API uses a simpler authentication model compared to the Issuing API:

• HTTP Basic Authentication - Username/password credentials
• Bearer Token (JWT) - Token-based authentication

Both authentication methods are supported. Choose the one that best fits your integration architecture.

---

​

Complete Workflow

​

Phase 1: Card Binding

Before processing any transactions, you must first bind a customer’s card to your merchant system. This is a one-time process per card.

​

Step 1: Initiate Card Binding

The merchant initiates the binding process by sending the customer’s full PAN (Primary Account Number). Response includes:

• verificationId - Unique identifier for this binding attempt
• code - Verification code sent to cardholder (also returned for testing)
• maskedPan - Masked card number for display
• codeExpiry - Expiration timestamp for the code

​

Step 2: Confirm Card Binding

The cardholder enters the verification code they received. The merchant submits this code along with the verificationId to complete the binding. Response includes:

• cardId - Critical: Store this UUID securely. It’s required for all future transactions with this card.
• bindingStatus - Confirms successful binding
• cardFace - Card brand image URL
• expirationDate - Card expiration date

​

Phase 2: Transaction Processing

Once a card is bound, you can process transactions. The transaction lifecycle follows a standard authorization-capture pattern with support for voids and refunds.

​

Transaction Lifecycle Diagram

The following diagram shows the complete transaction lifecycle:

​

Transaction Processing Steps

​

Step 1: Verify Transaction

Before authorizing a payment, verify the transaction parameters and trigger OTP delivery to the cardholder.

​

Step 2: Authorize Purchase

The cardholder enters the OTP code. The merchant submits the transaction details along with the OTP to authorize the payment. Response includes:

• transactionId - Critical: Store this UUID. Required for capture, release, or refund operations.
• status - Will be "locked" after successful authorization
• amountAuthorized - The amount that was authorized
• authorizationExpiry - When the authorization expires

​

Step 3: Capture Funds

After fulfilling the order or providing the service, capture the authorized funds to complete the payment. Important Notes:

• Capture must occur before authorizationExpiry
• You can capture less than the authorized amount (partial capture)
• Once captured, funds are transferred to your merchant account

​

Alternative: Release Authorization

If you need to cancel an order before fulfillment, release (void) the authorization to free the customer’s funds. Important Notes:

• Release can only be done on locked transactions
• Once released, the transaction cannot be captured
• This operation cannot be reversed

​

Step 4: Process Refunds (if needed)

For captured transactions, you can issue full or partial refunds. Important Notes:

• Refunds can only be processed on captured transactions
• You can issue multiple partial refunds up to the captured amount
• Each refund generates a unique refundTransactionId

---

​

Transaction Status Lifecycle

Understanding transaction statuses is crucial for proper integration:

​

Status Transition Rules

---

​

Integration Best Practices

​

Security

1. Never log sensitive data:
   • Full PANs
   • Verification codes (OTP)
   • Card IDs (store securely, don’t log)
2. Store securely:
   • cardId - Required for all future transactions
   • transactionId - Required for capture/release/refund operations
3. Handle expiration:
   • Verification codes expire (check codeExpiry)
   • Authorizations expire (check authorizationExpiry)

​

Error Handling

The API uses standard HTTP status codes with detailed error responses:

• 400 Bad Request - Invalid parameters or malformed request
• 404 Not Found - Resource doesn’t exist or invalid state
• 406 Not Acceptable - Transaction declined or failed
• 409 Conflict - Resource conflict (e.g., already bound)
• 500 Internal Server Error - Server-side error

Each error response includes a code and message field for programmatic handling.

​

Idempotency

• Card binding requests are idempotent - duplicate requests return the same verificationId
• Transaction operations should be idempotent on your side using unique identifiers

​

Timing Considerations

• Authorization expiry: Capture or release before authorizationExpiry
• Code expiry: Complete binding confirmation before codeExpiry
• Network timeouts: Implement retry logic with exponential backoff

---

​

Quick Reference

​

Card Binding Endpoints

​

Transaction Endpoints

---

​

Next Steps

• Explore the Card Binding endpoints to get started
• Review Transaction endpoints for payment processing
• Check the OpenAPI specification for complete API details