--- updatedAt: 2026-05-29T16:44:17.000Z --- Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further. # Create transfer Create a transfer operation between two accounts on the Pismo platform. With this endpoint, you have the following additional options. - Specify the `authentication` method and details. - Set `pre_authorization` to `true` for operations that require additional confirmation and then call the [Confirm pre-authorized transfer](ref:post-transfers-confirm) endpoint. - Set `validation_rules` in the `From` object to control the rules in this flow, such as disabling a rule, changing the response code and denial code, and forcing a rule. Refer to the [Payment methods](doc:payment-methods) guide for additional information. This endpoint generates a [Platform authorization created](https://developers.pismo.io/events/docs/platform-authorization-platform-authorization-1) event. **Note:** This is a PCI endpoint, use the https://gw-pci.pismolabs.io environment. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Core platform - Payment methods", "version": "1.0.0", "description": "API to handle payments.", "contact": { "name": "API Support", "url": "https://developers.pismo.io/support/" }, "license": { "name": "Copyright Pismo" } }, "servers": [ { "url": "https://sandbox.pismolabs.io", "description": "Sandbox API server for testing" }, { "url": "https://gw-pci.pismolabs.io", "description": "Sandbox PCI API server for testing" } ], "tags": [ { "name": "Payment methods", "description": "Endpoints to manage cash-in and cash-out payments and P2P transfers." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Account access token. Tokens can expire quickly, which can result in an \"Unauthorized\" error.", "bearerFormat": "JWT" } }, "schemas": { "ValidationRules": { "type": "object", "description": "Validation rules performed in the flow. Each key is a rule name (such as `ACCOUNT_STATUS` or `LEDGER`) and the value is its configuration.", "additionalProperties": { "$ref": "#/components/schemas/RuleConfig" }, "example": { "ACCOUNT_STATUS": { "disable": false, "force": false, "denial_reasons": { "ACCOUNT_STATUS_NOT_PERMITTED": { "response_code": "57", "denial_code": "DAL" } } }, "LEDGER": { "denial_reasons": { "LEDGER_INSUFFICIENT_FUNDS": { "response_code": "51", "denial_code": "DAL" }, "LEDGER_NOT_ALLOWED_OPERATION": { "response_code": "57", "denial_code": "DAL" } } } } }, "RuleConfig": { "type": "object", "description": "Configuration related to a rule.", "properties": { "denial_reasons": { "$ref": "#/components/schemas/DenialReasons" }, "disable": { "type": "boolean", "description": "Flag to disable this rule throughout Payments validation flow." }, "force": { "type": "boolean", "description": "Flag to force this rule throughout Payments validation flow." } } }, "DenialReasons": { "type": "object", "description": "Denial reasons linked to a rule.", "additionalProperties": { "$ref": "#/components/schemas/ReasonConfig" } }, "ReasonConfig": { "type": "object", "properties": { "denial_code": { "type": "string", "description": "Denial code that must be used when this denial reason is the one that caused the request to be denied.", "example": "DAL" }, "response_code": { "type": "string", "description": "Response code that must be used when this denial reason is the one that caused the request to be denied.", "example": "57" } } }, "AccountID": { "description": "Pismo account ID.", "type": "integer", "format": "int64", "example": 8675309 }, "Amount": { "type": "number", "format": "float", "description": "Credit or debit amount.", "example": 100.23 }, "DenialCode": { "type": "string", "description": "Denial code.", "example": "DAL" }, "Description": { "type": "string", "description": "Optional text that describes the operation.", "example": "Custom purchase." }, "CurrencyPismoHierarchy": { "type": "string", "description": "ISO-4217 alphabetic or numeric (3 characters) authorization currency code. For example, either BRL or 986 for Brazilian real. If you don't provide the currency, the platform uses the currency registered in the Pismo hierarchy (first looking at the account, then program, and then Org levels).", "example": "BRL" }, "Metadata": { "type": "object", "description": "This optional user-defined key-value object field can be used with external operations to provide additional context or supplementary custom information for the operation. \n\nThe Pismo platform does not perform any validation or processing on this field but passes this object to the acquirer in transactions involving calls to the acquirer and sends it in the events related to the stream of data produced at the end of the request.\n\n**Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](https://developers.pismo.io/pismo-docs/reference/get-started-with-pismo-apis#metadata).\n", "example": { "any-key": "any-value" } }, "PaymentDatetime": { "type": "string", "format": "date-time", "description": "Effective payment date in the UTC-0 RFC3339 format, which includes milliseconds (yyyy-MM-ddThh:mm:ss.SSSZ).\nPayments can be backdated but future dates are not allowed.\n", "example": "2023-01-02T07:35:05.125Z" }, "ProcessingCode": { "type": "string", "description": "Unique processing code that identifies the credit or debit operation.", "example": "219803" }, "ResponseCode": { "type": "string", "description": "Alphanumeric two-character standard card network response code or an alternative custom response code, which provides the precise reason for the success or denial of the operation by the card network, platform, or anti-fraud solution.\n", "example": "57" }, "TrackingID": { "type": "string", "description": "Unique tracking ID for this operation.", "minLength": 36, "maxLength": 50, "example": "0b6995e5-b417-9be4-92b3-3677f4440ebe" }, "ValidationResults": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the evaluated rule.", "example": "LEDGER" }, "status": { "type": "string", "enum": [ "APPROVED", "REJECTED", "SKIPPED" ], "description": "Identifies if the rule was approved, rejected, or skipped during the validation flow.", "example": "REJECTED" }, "reason": { "type": "string", "description": "Status reason why the specific rule was approved, rejected, or skipped.", "example": "LEDGER_INSUFFICIENT_FUNDS" }, "description": { "type": "string", "description": "Description of the validation result.", "example": "The authorization amount is greater than the account available limit." }, "additional_data": { "description": "Additional data for the validation result. This varies from validation to validation, but every denied validation has the `denial_code` and `response_code` fields.", "type": "object" } } } }, "PreAuthorization": { "type": "boolean", "description": "If set to `true`, this flag indicates that the operation is pre-authorized and requires additional confirmation.", "default": false, "example": false }, "AuthorizationValidations": { "type": "object", "description": "Contains additional data to be used in the authorization flow. This field is only considered for authorizations. Cancellations and confirmations will retrieve it based on the original authorization.", "properties": { "is_device_registered": { "description": "Indicates whether the device used for the operation is registered according to the financial institution's security policies.", "type": "boolean", "example": true }, "associated_ids": { "$ref": "#/components/schemas/AssociatedIDs" } } }, "AssociatedIDs": { "type": "object", "description": "External IDs used in the authorization flow.", "properties": { "payment_id": { "description": "External ID associated with the authorization.", "type": "string", "example": "319d00f5-48de-4c71-ad47-40b1e9c4e37f" }, "origin_id": { "description": "External ID of the origin of the authorization.", "type": "string", "example": "CUSTOM_ORIGIN" } } }, "Authentication": { "type": "object", "description": "Authentication object.", "properties": { "method": { "type": "string", "description": "Authentication method. \n- `otp` is when the operation needs to be authenticated.\n- `transaction_signing` is when the operation has been authenticated already but needs to be validated.\n", "example": "otp" }, "parameters": { "type": "object", "description": "Authentication parameters will vary, depending on type of the method used.", "properties": { "device_id": { "type": "string", "description": "Device ID. Used in the `otp` authentication method.", "example": "abc" }, "token": { "type": "string", "description": "Authentication token. Used in the `otp` authentication method.", "example": "123456" }, "user_id": { "type": "string", "description": "User ID. Used in the `otp` authentication method.", "example": "123456789" }, "hash": { "type": "string", "description": "Value generated at the time of authentication via OTP and intended for authentication via signing. Used in the `transaction_signing` authentication method." }, "signing_data": { "type": "object", "description": "Object that contains authorization information provided at time of signing. Used in the `transaction_signing` authentication method." } } } } }, "BeneficiaryID": { "type": "string", "description": "UUID for the beneficiary related to the account.", "minLength": 36, "maxLength": 50, "example": "2c298321-bc21-4039-9c45-780cc6d4ec46" }, "From": { "type": "object", "required": [ "processing_code", "account_id" ], "properties": { "account_id": { "$ref": "#/components/schemas/AccountID" }, "currency": { "$ref": "#/components/schemas/CurrencyPismoHierarchy" }, "processing_code": { "$ref": "#/components/schemas/ProcessingCode" }, "validation_rules": { "$ref": "#/components/schemas/ValidationRules" }, "authorization_validations": { "$ref": "#/components/schemas/AuthorizationValidations" } } }, "To": { "type": "object", "required": [ "processing_code", "account_id" ], "properties": { "account_id": { "$ref": "#/components/schemas/AccountID" }, "beneficiary_id": { "$ref": "#/components/schemas/BeneficiaryID" }, "currency": { "$ref": "#/components/schemas/CurrencyPismoHierarchy" }, "processing_code": { "$ref": "#/components/schemas/ProcessingCode" }, "validation_rules": { "$ref": "#/components/schemas/ValidationRules" }, "authorization_validations": { "type": "object", "description": "Contains additional data to be used in the authorization flow. This field is only considered for authorizations. Cancellations and confirmations will retrieve it based on the original authorization.", "properties": { "associated_ids": { "$ref": "#/components/schemas/AssociatedIDs" } } } } }, "v2PaymentsResponse": { "type": "object", "description": "Response for a cash-in or cash-out operation.", "required": [ "tracking_id", "amount", "response_code" ], "properties": { "tracking_id": { "$ref": "#/components/schemas/TrackingID" }, "account_id": { "$ref": "#/components/schemas/AccountID" }, "response_code": { "$ref": "#/components/schemas/ResponseCode" }, "denial_code": { "$ref": "#/components/schemas/DenialCode" }, "validation_results": { "$ref": "#/components/schemas/ValidationResults" } }, "example": { "tracking_id": "634c43f2-5b7e-4a80-81c7-e6a7d5edc7fe", "account_id": 456, "amount": 1000, "response_code": "00", "denial_code": "LE003", "validation_results": [ { "name": "ACCOUNT", "status": "APPROVED", "reason": "ACCOUNT_FOUND", "description": "Account was found.", "additional_data": { "account_id": 2417 } }, { "name": "ACCEPTANCE", "status": "APPROVED", "reason": "ACCEPTANCE_FOUND", "description": "Payment methods acceptances were found." }, { "name": "CONFIG", "status": "APPROVED", "reason": "CONFIG_FOUND", "description": "Payment methods configuration was found." }, { "name": "PAYMENT_DATE", "status": "SKIPPED", "reason": "PAYMENT_DATE_SKIPPED", "description": "Payment date validation was skipped.", "additional_data": { "cause": "Payment date not present." } }, { "name": "PLATFORM_AUTHENTICATION", "status": "APPROVED", "reason": "PLATFORM_AUTHENTICATION_SUCCESSFUL", "description": "Request was authenticated successfully." }, { "name": "ACCOUNT_ID", "status": "APPROVED", "reason": "ACCOUNT_ID_PERMITTED", "description": "Account ID is permitted.", "additional_data": { "document_number": "60XXXXXXXXX19", "external_id": "", "name": "Marcelito" } }, { "name": "PROCESSING_CODE", "status": "APPROVED", "reason": "PROCESSING_CODE_FOUND", "description": "Processing code was found." }, { "name": "PROCESSING_CODE_TYPE", "status": "APPROVED", "reason": "PROCESSING_CODE_TYPE_VALID", "description": "Processing code has a valid balance impact type." }, { "name": "ACCOUNT_LIMITS", "status": "APPROVED", "reason": "ACCOUNT_LIMITS_FOUND", "description": "Account limits were found.", "additional_data": { "available_credit_limit": 746847632710983.1, "available_savings_account_limit": 93477.42, "available_total_installment_credit": -226, "available_withdrawal_credit": -175, "total_credit_limit": 1000, "total_installment_credit_limit": 200, "withdrawal_credit_limit": 300 } }, { "name": "ACCOUNT_STATUS", "status": "APPROVED", "reason": "ACCOUNT_STATUS_PERMITTED", "description": "Account status is permitted." }, { "name": "PROGRAM", "status": "APPROVED", "reason": "PROGRAM_FOUND", "description": "Program was found.", "additional_data": { "program_type": "PRE-PAGO" } }, { "name": "BALANCES_CONFIG", "status": "APPROVED", "reason": "BALANCES_CONFIG_FOUND", "description": "Balances configuration was found.", "additional_data": { "amount": "contract_amount", "amount_consider": "principal_amount", "consider": [ "AvailableCreditLimit", "OverLimit" ], "impact": [ "AvailableCreditLimit" ], "reset_limit": "last_installment" } }, { "name": "CURRENCY", "status": "APPROVED", "reason": "CURRENCY_FOUND", "description": "Currency was found.", "additional_data": { "code": "BRL", "numeric_code": "986" } }, { "name": "RATES", "status": "APPROVED", "reason": "RATES_APPROVED", "description": "Rates calculation was performed.", "additional_data": { "conversion": { "conversion_rate": 0, "destination": "986", "exchange_rate": 1, "origin": "986", "spread": 0 } } }, { "name": "FLEX_CONTROLS", "status": "APPROVED", "reason": "FLEX_CONTROLS_APPROVED", "description": "Authorization passed flex control evaluation.", "additional_data": { "dry_run": false, "evaluated_controls": [ { "id": "bb975c75-ae31-48e8-ac0b-57c677fdd0e4", "name": "Purchase 1 Month credit card", "evaluation_result": true, "deny_code": "MAX_VALUE_P1M", "response_code": "63", "max_limit": 200000, "accumulated_limit": 135127, "available_limit": 64873 } ] } }, { "name": "LEDGER", "status": "APPROVED", "reason": "LEDGER_APPROVED", "description": "Ledger was impacted successfully.", "additional_data": { "dry_run": false, "validation_results": null, "account_id": 9999, "available_amounts": { "validation_status": "APPROVED", "details": { "result": { "available_credit_limit": 746847527710892.1, "available_installment_limit": -226, "available_savings_account_limit": 93477.42, "available_withdraw_limit": -175, "held_funds": 91.25, "additional_funds": 0, "overlimit": 2000000, "total_overdraft_limit": 0 } } } }, "ledger_operation_status": { "validation_status": "APPROVED" } }, { "name": "AUTHORIZATION", "status": "APPROVED", "reason": "AUTHORIZATION_CREATED", "description": "Authorization was created successfully." } ] } }, "401Transfers": { "type": "object", "description": "Error codes available:\n * WONT0005 - Authentication is required but no authentication method was provided.\n * WONT0006 - Authentication is required but it was not performed.\n * WONT0007 - Request was not authenticated.\n", "properties": { "code": { "type": "string", "example": "WONT0005", "enum": [ "WONT0005", "WONT0006", "WONT0007" ] }, "message": { "type": "string", "example": "Authentication is required but no authentication method was provided.", "enum": [ "Authentication is required but no authentication method was provided.", "Authentication is required but it was not performed.", "Request was not authenticated." ] } } }, "409Transfers": { "type": "object", "description": "Error codes available:\n * WONT0003 - Tracking ID was already used.\n * WONT0004 - Tracking ID is already in use by an ongoing request.\n", "properties": { "code": { "type": "string", "example": "WONT0003", "enum": [ "WONT0003", "WONT0004" ] }, "message": { "type": "string", "example": "Tracking ID is already in use by an ongoing request.", "enum": [ "Tracking ID was already used.", "Tracking ID is already in use by an ongoing request." ] } } }, "TransfersRequest": { "type": "object", "description": "Request an authorization processing", "required": [ "tracking_id", "amount", "to", "from" ], "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "from": { "$ref": "#/components/schemas/From" }, "to": { "$ref": "#/components/schemas/To" }, "tracking_id": { "$ref": "#/components/schemas/TrackingID" }, "authentication": { "$ref": "#/components/schemas/Authentication" }, "description": { "$ref": "#/components/schemas/Description" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "payment_datetime": { "$ref": "#/components/schemas/PaymentDatetime" }, "pre_authorization": { "$ref": "#/components/schemas/PreAuthorization" } } }, "TransfersResponse": { "type": "object", "properties": { "tracking_id": { "$ref": "#/components/schemas/TrackingID" }, "response_code": { "$ref": "#/components/schemas/ResponseCode" }, "denial_code": { "$ref": "#/components/schemas/DenialCode" }, "from": { "$ref": "#/components/schemas/v2PaymentsResponse" }, "to": { "$ref": "#/components/schemas/v2PaymentsResponse" } } }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Application-specific error code" }, "message": { "type": "string", "description": "Error explanation" }, "violations": { "type": "object", "description": "Field-level validation failures (keys are dynamic)", "additionalProperties": { "type": "string" } } }, "required": [ "code", "message" ] } } }, "security": [ { "BearerAuth": [] } ], "paths": { "/payment-methods/v2/transfers": { "post": { "summary": "Create transfer", "description": "Create a transfer operation between two accounts on the Pismo platform.\n\nWith this endpoint, you have the following additional options.\n- Specify the `authentication` method and details.\n- Set `pre_authorization` to `true` for operations that require additional confirmation and then call the [Confirm pre-authorized transfer](https://developers.pismo.io/pismo-docs/reference/post-transfers-confirm) endpoint.\n- Set `validation_rules` in the `From` object to control the rules in this flow, such as disabling a rule, changing the response code and denial code, and forcing a rule.\n\nRefer to the [Payment methods](https://developers.pismo.io/pismo-docs/docs/payment-methods) guide for additional information.\n\nThis endpoint generates a [Platform authorization created](https://developers.pismo.io/events/docs/platform-authorization-platform-authorization-1) event.\n\n**Note:** This is a PCI endpoint, use the https://gw-pci.pismolabs.io environment.\n", "operationId": "post-transfers", "tags": [ "Payment methods" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransfersRequest" } } } }, "responses": { "200": { "description": "Request was processed successfully, existing authorization with the corresponding `tracking_id` returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransfersResponse" } } } }, "201": { "description": "Request was processed successfully, new authorization created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransfersResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Amount required": { "value": { "code": "WONP0001", "message": "Payload is invalid. It must be a valid JSON.", "violations": { "amount": "amount is a required field." } } }, "Invalid amount": { "value": { "code": "WONP0001", "message": "Payload is invalid. It must be a valid JSON.", "violations": { "amount": "A maximum of 20 digits, including two decimals, is allowed for the amount field." } } }, "Invalid account": { "value": { "code": "WONB0001", "message": "Authorized account is different from the request." } }, "Invalid currency": { "value": { "code": "WONP0001", "message": "Payload is invalid. It must be a valid JSON.", "violations": { "currency": "Currency is invalid. The field must have the valid ISO 4217 currency code." } } }, "Tracking ID required": { "value": { "code": "WONP0001", "message": "Payload is invalid. It must be a valid JSON.", "violations": { "tracking_id": "tracking_id is a required field." } } }, "Processing code required": { "value": { "code": "WONP0001", "message": "Payload is invalid. It must be a valid JSON.", "violations": { "processing_code": "processing_code is a required field." } } } } } } }, "401": { "description": "Access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/401Transfers" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/409Transfers" } } } }, "422": { "description": "Unprocessable request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Unprocessable authentication method": { "value": [ { "code": "EPAE0004", "message": "The method provided in the payload does not exist." } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Platform authentication unexpected error": { "value": [ { "code": "EPAE0001", "message": "Unexpected error while processing the call to the authentication system." } ] }, "Platform authentication timeout error": { "value": [ { "code": "EPAE0002", "message": "Timeout error while processing the call to the authentication system." } ] } } } } } } } } } } ```