---
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 payment request

Create a new payment request. Once created, call the [Transfer funds](ref:post-payments-v1-payments) endpoint to execute the payment.

For additional information, see the [Payment requests](doc:payment-requests) guide.


# 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 requests",
      "description": "APIs to manage payment requests."
    }
  ],
  "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": {
      "ErrorModel": {
        "description": "API generic returned error.",
        "type": "object",
        "properties": {
          "error_code": {
            "type": "string",
            "description": "Error code.",
            "deprecated": true
          },
          "code": {
            "type": "string",
            "description": "Error code."
          },
          "message": {
            "type": "string",
            "description": "Error description."
          }
        },
        "title": "ErrorModel"
      },
      "Location": {
        "properties": {
          "lat": {
            "description": "Request latitude.",
            "type": "number",
            "format": "float",
            "example": 12.2
          },
          "lng": {
            "description": "Request longitude.",
            "type": "number",
            "format": "float",
            "example": -12.2
          }
        },
        "description": "Request latitude and longitude object.",
        "title": "Location"
      },
      "PaymentMethodAccount": {
        "title": "PaymentMethodAccount",
        "type": "object",
        "description": "Payment method for Pismo account transfers.",
        "properties": {
          "account": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "description": "Pismo platform account ID.",
                "example": 101
              }
            },
            "required": [
              "id"
            ]
          },
          "amount": {
            "description": "Credit or debit amount.",
            "type": "number",
            "format": "float",
            "example": 12.13
          },
          "processing_code": {
            "description": "Optional for use with private acceptance/acquiring merchant networks. \nCan be used to define a different settlement condition (MDR, days to settle, and so on). \nFor details, see acquiring/marketplace documentation.\n",
            "type": "string",
            "example": "004000",
            "pattern": "^[0-9]{6}$"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "beneficiary_id": {
            "type": "string",
            "example": "2c298321-bc21-4039-9c45-780cc6d4ec46",
            "description": "Unique string identifier for the beneficiary associated with the account."
          }
        }
      },
      "PaymentRequestModel": {
        "title": "PaymentRequestModel",
        "type": "object",
        "description": "Payload object for Create payment request (`v1/payment-requests`).",
        "properties": {
          "to": {
            "$ref": "#/components/schemas/PaymentMethodAccount"
          },
          "from": {
            "$ref": "#/components/schemas/PaymentMethodAccount"
          },
          "amount": {
            "type": "number",
            "format": "float",
            "description": "Payment request amount.",
            "minimum": 0.01,
            "example": 9.95
          },
          "processing_code": {
            "type": "string",
            "example": "004000",
            "description": "Payment request processing code."
          },
          "expiration": {
            "type": "string",
            "format": "date-time",
            "example": "2020-05-11T10:39:00.000Z",
            "description": "Payment request expiration date in UTC-0 (RFC3339) format."
          },
          "tracking_id": {
            "type": "string",
            "description": "Optional unique ID correlating the payment request's associated credit and debit authorizations.",
            "example": "1ff51e99-3a05-448a-bc19-7b5c05274174"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          },
          "location": {
            "$ref": "#/components/schemas/Location"
          }
        },
        "required": [
          "to",
          "amount"
        ]
      },
      "PaymentRequestResponse": {
        "title": "PaymentRequestResponse",
        "type": "object",
        "description": "Response object from Create payment request (`v1/payment-requests`).",
        "properties": {
          "type": {
            "type": "string",
            "description": "Payment request format type.",
            "example": "TOKEN"
          },
          "code": {
            "type": "string",
            "description": "Payment request ID code. Token field for Transfer funds (`v1/payments`)",
            "example": "a78f0809-7a22-4485-8e57-abf70168c5f0"
          }
        }
      },
      "Currency": {
        "type": "string",
        "description": "ISO-4217 alphabetic or numeric (3 characters) operation currency code. For example, either BRL or 986 for Brazilian real.",
        "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"
        }
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/payments/v1/payment-requests": {
      "post": {
        "operationId": "post-payments-v1-payment-requests",
        "summary": "Create payment request",
        "description": "Create a new payment request. Once created, call the [Transfer funds](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-payments) endpoint to execute the payment.\n\nFor additional information, see the [Payment requests](https://developers.pismo.io/pismo-docs/docs/payment-requests) guide.\n",
        "tags": [
          "Payment requests"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "minLength": 39,
              "maxLength": 39,
              "type": "string",
              "example": "TN-c0e4c660-9059-404c-ab22-761aa431766c",
              "pattern": "TN\\-[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}"
            },
            "in": "header",
            "name": "x-tenant",
            "description": "Unique Org ID.",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "header",
            "name": "x-account-id",
            "description": "Source account ID (optional). Can be ommited if `from` specifies the source account ID."
          },
          {
            "schema": {
              "type": "string",
              "example": "c737895c-8159-4c0c-a92a-a4f8600bff37"
            },
            "in": "header",
            "name": "x-cid",
            "description": "Related correlation identifier. If none is provided, a random one is generated."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentRequestModel"
              },
              "examples": {
                "Sample Payload": {
                  "value": {
                    "amount": 10,
                    "to": {
                      "currency": "BRL",
                      "account": {
                        "id": 1234
                      }
                    },
                    "expiration": "2021-12-31T10:00:00.000Z",
                    "location": {
                      "lat": 12.2,
                      "lng": -12.2
                    },
                    "metadata": {
                      "my-custom-key": "my-custom-value01"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequestResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                },
                "examples": {
                  "Mandatory source error": {
                    "value": {
                      "error_code": "WP2P0000",
                      "code": "WP2P0000",
                      "message": "Source account is required"
                    }
                  },
                  "Mandatory destination error": {
                    "value": {
                      "error_code": "WP2P0000",
                      "code": "WP2P0000",
                      "message": "Destination account is required"
                    }
                  },
                  "Payment request already settled": {
                    "value": {
                      "error_code": "WP2P0000",
                      "code": "WP2P0000",
                      "message": "Payment request already settled"
                    }
                  },
                  "Invalid amount": {
                    "value": {
                      "error_code": "WP2P0000",
                      "code": "WP2P0000",
                      "message": "The amount must have a maximum of two decimal places."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                },
                "examples": {
                  "Database connection error": {
                    "value": {
                      "error_code": "WP2P0000",
                      "code": "WP2P0000",
                      "message": "Database connection error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```