--- updatedAt: 2026-05-15T19:08:46.000Z agentTools: siteIndex: https://developers.pismo.io/llms.txt projectIndex: https://developers.pismo.io/pismo-docs/llms.txt --- # Transfer UPI funds United Payments Interface (UPI) funds transfer for RuPay, an Indian card network. Before calling this endpoint, you can call [List cards](ref:post-list-cards) to get the `account_reference_number`. You should also call [Validate card](ref:post-validate-card-data) to make sure the card data for the transfer request is genuine. This endpoint generates a [Payment methods authorization created](https://developers.pismo.io/events/docs/payment-methods-authorization-1) event and a [Platform authorization created](https://developers.pismo.io/events/docs/platform-authorization-platform-authorization-1) event. This operation is **idempotent**, meaning, it can be applied multiple times, yet the outcome remains the same. To guarantee this, the request has an `external_transaction_id` field, which must be unique by transaction type in the context of the same account reference number. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Instant payments - RuPay on UPI", "description": "United Payments Interface (UPI) API integrating providers with the Pismo platform", "contact": { "name": "Pismo" }, "license": { "name": "Apache 2.0" }, "version": "1.0" }, "servers": [ { "url": "https://sandbox.pismolabs.io/upi-gateway", "description": "Sandbox API server for testing" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "UPI", "description": "Endpoints to manage UPI operations" } ], "components": { "parameters": { "AuthHeader": { "in": "header", "name": "Authorization", "required": true, "description": "Authorization token. Tokens can expire quickly, which can result in a **401 Unauthorized** message.", "schema": { "type": "string", "example": "Bearer eyJhbGci...IUzUx" } }, "UserAgentHeader": { "in": "header", "name": "user-agent", "required": true, "description": "Client consuming API.", "schema": { "type": "string" } } }, "schemas": { "accountReferenceNumber": { "type": "string", "description": "\nAccount reference number. Pismo creates this automatically when creating a card linked to RuPay on UPI.\n\nThis number combines 10 BIN digits and the credit account number. If BIN is 6 digits, the remaining 4 digits are set to zero (`0`). If BIN is 8 digits, then the remaining 2 digits are set to zero. This is a [NPCI](https://www.npci.org.in/what-we-do/rupay/product-overview) standard. For example, if the account reference number = `1234560000987654321`, the first six digits are the BIN, appended with 4 zeros and then the credit account number (`987654321``).\n\nYou can call [List cards](https://developers.pismo.io/pismo-docs/reference/post-list-cards) to get a card's account reference number.\n", "example": "12345600000000001140340134" }, "authorizationDatetime": { "type": "string", "format": "datetime", "description": "When transfer was authorised. RFC 3339 format." }, "authorizationID": { "type": "number", "description": "Authorization ID", "example": 2263052808 }, "cards.TransferRequest": { "type": "object", "required": [ "amount", "currency", "account_reference_number", "external_transaction_datetime", "external_transaction_id", "mcc", "merchant_name", "phone", "transaction_type", "upi_reference_number" ], "properties": { "amount": { "type": "number", "description": "Transaction amount", "example": 500 }, "currency": { "type": "string", "description": "Transaction currency. ISO 4217 3-digit currency code. For example - `INR` (Indian rupee)", "example": "INR" }, "account_reference_number": { "$ref": "#/components/schemas/accountReferenceNumber" }, "external_transaction_datetime": { "$ref": "#/components/schemas/externalTransactionDatetime" }, "external_transaction_id": { "$ref": "#/components/schemas/externalTransactionID" }, "mcc": { "type": "string", "description": "Transaction Merchant Category Code (MCC)", "example": "6012" }, "merchant_name": { "type": "string", "description": "Merchant name", "example": "Cafe Coffee Day" }, "merchant": { "$ref": "#/components/schemas/merchant" }, "phone": { "$ref": "#/components/schemas/phone" }, "transaction_type": { "$ref": "#/components/schemas/transactionType" }, "upi_reference_number": { "$ref": "#/components/schemas/upiReferenceNumber" }, "transaction_reference": { "type": "string", "description": "Transaction reference", "example": "Lunch" }, "credit_account_number": { "type": "string", "description": "Payee account number if available", "example": "98765004371" } } }, "cards.TransferResponse": { "type": "object", "required": [ "external_transaction_id", "status", "upi_reference_number" ], "properties": { "external_transaction_id": { "$ref": "#/components/schemas/externalTransactionID" }, "status": { "$ref": "#/components/schemas/transactionStatus" }, "upi_reference_number": { "$ref": "#/components/schemas/upiReferenceNumber" }, "authorization_id": { "$ref": "#/components/schemas/authorizationID" }, "authorization_datetime": { "$ref": "#/components/schemas/authorizationDatetime" } } }, "domain.DetailMessage": { "type": "object", "properties": { "external": { "type": "array", "items": { "$ref": "#/components/schemas/domain.ExternalMessage" } }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/domain.ParameterMessage" } }, "payload": { "type": "array", "items": { "$ref": "#/components/schemas/domain.PayloadMessage" } } } }, "domain.Error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error type code", "example": "EPT0001" }, "details": { "type": "object", "description": "Detailed error message", "allOf": [ { "$ref": "#/components/schemas/domain.DetailMessage" } ] }, "message": { "type": "string", "description": "Error message", "example": "User not found" } } }, "domain.ExternalMessage": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Code", "example": "PBE315" }, "message": { "type": "string", "description": "Message", "example": "Generic error" } } }, "domain.ParameterMessage": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string", "description": "Field", "example": "Query parameter" }, "message": { "type": "string", "description": "Message", "example": "Generic error" } } }, "domain.PayloadMessage": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string", "description": "Field", "example": "Entity.field" }, "message": { "type": "string", "description": "Error message", "example": "Generic error" } } }, "externalTransactionDatetime": { "type": "string", "description": "Request datetime. ISO 8601 format.", "example": "2020-09-15T19:39:54.013Z" }, "externalTransactionID": { "type": "string", "description": "Request ID code", "example": "MGS584A1244F6BC4D50A3FABE6D93DF913C" }, "merchant": { "type": "object", "properties": { "mid": { "type": "string", "description": "Merchant ID number", "example": "HDFC000018966129" }, "tid": { "type": "string", "description": "Terminal ID", "example": "42284754" }, "sid": { "type": "string", "description": "Service ID - payment network (like NPCI) assigned unique code to a merchant or service provider.", "example": "18994373" } } }, "phone": { "type": "object", "required": [ "country_code", "phone" ], "properties": { "country_code": { "type": "string", "description": "Phone number country code", "example": "55" }, "phone": { "type": "string", "description": "Phone number", "example": "999167803" }, "area_code": { "type": "string", "description": "Phone number area code", "example": "47" } }, "example": { "country_code": "91", "phone": "9592714958" } }, "transactionStatus": { "type": "string", "description": "Transaction status", "enum": [ "PROCESSING", "ACCEPTED", "ERROR", "CANCELLED" ], "example": "PROCESSING" }, "transactionType": { "type": "string", "description": "Transaction type:\n * `C` - Credit\n * `D` - Debit\n * `R` - Reversal\n * `E` - Equated monthly installments (EMI)\n * `F` - Foreclose\n", "enum": [ "C", "D", "R", "E", "F" ], "example": "C" }, "upiReferenceNumber": { "type": "string", "description": "UPI reference number", "minLength": 12, "maxLength": 12, "example": "165238546812" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Account token - token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a **401 Unauthorized** error.\n", "bearerFormat": "JWT" } } }, "paths": { "/v1/cards/transfer": { "post": { "summary": "Transfer UPI funds", "description": "United Payments Interface (UPI) funds transfer for RuPay, an Indian card network.\n\nBefore calling this endpoint, you can call [List cards](https://developers.pismo.io/pismo-docs/reference/post-list-cards) to get the `account_reference_number`. You should also call [Validate card](https://developers.pismo.io/pismo-docs/reference/post-validate-card-data) to make sure the card data for the transfer request is genuine.\n\nThis endpoint generates a [Payment methods authorization created](https://developers.pismo.io/events/docs/payment-methods-authorization-1) event and a [Platform authorization created](https://developers.pismo.io/events/docs/platform-authorization-platform-authorization-1) event.\n\nThis operation is **idempotent**, meaning, it can be applied multiple times, yet the outcome remains the same. To guarantee this, the request has an `external_transaction_id` field, which must be unique by transaction type in the context of the same account reference number. \n", "operationId": "post-funds-transfer", "tags": [ "UPI" ], "parameters": [ { "$ref": "#/components/parameters/AuthHeader" }, { "$ref": "#/components/parameters/UserAgentHeader" } ], "requestBody": { "description": "Request Body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cards.TransferRequest" } } }, "required": true }, "responses": { "201": { "description": "Transfer created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cards.TransferResponse" }, "example": { "upi_reference_number": "165238546812", "external_transaction_id": "MGS584A1244F6BC4D50A3FABE6D93DF913C", "authorization_id": 2263052808, "authorization_datetime": "2024-09-04T13:22:09.579Z", "status": "ACCEPTED" } } } }, "202": { "description": "It is returned for duplicated requests, when the transfer is still being processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cards.TransferResponse" }, "example": { "upi_reference_number": "165238546812", "external_transaction_id": "MGS584A1244F6BC4D50A3FABE6D93DF913C", "status": "PROCESSING" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domain.Error" }, "examples": { "EUPI0002": { "summary": "Validation error", "value": { "code": "EUPI0002", "message": "Validation error", "details": { "payload": [ { "field": "external_transaction_id", "message": "Field 'external_transaction_id' is required" } ] } } }, "EUPI0003": { "summary": "Bad request", "value": { "code": "EUPI0003", "message": "Bad request" } }, "EUPI0104": { "summary": "Invalid transaction type", "value": { "code": "EUPI0104", "message": "Invalid transaction type" } }, "EUPI0101": { "summary": "The transaction was cancelled due authorization request validation error", "value": { "code": "EUPI0101", "message": "The transaction was cancelled due authorization request validation error" } }, "EUPI0108": { "summary": "The transaction was cancelled due to authorization error", "value": { "code": "EUPI0108", "message": "The transaction was cancelled due to an authorization error" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domain.Error" }, "examples": { "EUPI0120": { "summary": "Transfer amount is greater than the account available limits", "value": { "code": "EUPI0120", "message": "Transfer amount is greater than the account available limits" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domain.Error" }, "examples": { "EUPI0004": { "summary": "Missing required header 'x-tenant'", "value": { "code": "EUPI0004", "message": "Missing required header 'x-tenant'" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domain.Error" }, "examples": { "EUPI0110": { "summary": "Original transaction not found on reversal operation", "value": { "code": "EUPI0110", "message": "Original transaction not found on reversal operation" } } } } } }, "408": { "description": "Timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domain.Error" }, "examples": { "EUPI0020": { "summary": "Upi - API returned a timeout error", "value": { "code": "EUPI0020", "message": "Upi - API returned a timeout error" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domain.Error" }, "examples": { "EUPI0100": { "summary": "Transaction already exists with the external_transaction_id", "value": { "code": "EUPI0100", "message": "Transaction already exists with the external_transaction_id" } }, "EUPI0112": { "summary": "Original transaction is still being processed", "value": { "code": "EUPI0112", "message": "Original transaction is still being processed" } }, "EUPI0113": { "summary": "Original transaction is not accepted, then it can't be reverted", "value": { "code": "EUPI0113", "message": "Original transaction is not accepted, then it can't be reverted" } }, "EUPI0114": { "summary": "Reversal transaction amount must be equals to the original transaction", "value": { "code": "EUPI0114", "message": "Reversal transaction amount must be equals to the original transaction" } }, "EUPI0121": { "summary": "Invalid card status", "value": { "code": "EUPI0121", "message": "Invalid card status" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domain.Error" }, "examples": { "EUPI0001": { "summary": "An unexpected error happened", "value": { "code": "EUPI0001", "message": "An unexpected error happened" } }, "EUPI0105": { "summary": "The transaction will be cancelled due to internal error", "value": { "code": "EUPI0105", "message": "The transaction will be cancelled due to internal error" } }, "EUPI0106": { "summary": "The transaction was authorized but will be canceled due to internal error", "value": { "code": "EUPI0106", "message": "The transaction was authorized but will be canceled due to internal error" } } } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domain.Error" }, "examples": { "EUPI0109": { "summary": "The transaction will be cancelled due to authorization error", "value": { "code": "EUPI0109", "message": "The transaction will be cancelled due to authorization error" } } } } } } } } } } } ```