---
title: "Create cash-in or cash-out"
method: POST
path: "/payment-methods/v2/payments"
tags: ["Payment methods"]
---

# Create cash-in or cash-out

`POST /payment-methods/v2/payments`

## Request

- Base URL: `https://sandbox.pismolabs.io`
- URL: `https://sandbox.pismolabs.io/payment-methods/v2/payments`
- Auth: HTTP bearer

Create a cash-in or cash-out payment operation. The type of operation depends on the processing code (credit for cash-in and debit for cash-out). 
- For cash-in operations, the processing code must be of credit type. When [creating a processing code](ref:createprocessingcode), ensure that the `balance_impact` is `1` (credit).
- For cash-out operations, the processing code must be of debit type. When [creating a processing code](ref:createprocessingcode), ensure that the `balance_impact` is `-1` (debit).

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 cash-in or cash-out](ref:post-payment-confirm) endpoint.
- Set `validation_rules` 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) and [Payment configurations](doc:payments-configurations) guides 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.

## Request body

- PaymentsRequest: Request authorization processing for a cash-in or cash-out operation.
  - `account_id` integer, required: Pismo account ID.
  - `beneficiary_id` string: UUID for the beneficiary related to the account.
  - `amount` number, float, required: Credit or debit amount.
  - `currency_code` string: 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).
  - `processing_code` string, required: Unique processing code that identifies the credit or debit operation.
  - `tracking_id` string, required: Unique tracking ID for this operation.
  - `authentication` Authentication: Authentication object.
    - `method` string: Authentication method. - `otp` is when the operation needs to be authenticated. - `transaction_signing` is when the operation has been authenticated already but needs to be validated.
    - `parameters` object: Authentication parameters will vary, depending on type of the method used.
      - `device_id` string: Device ID. Used in the `otp` authentication method.
      - `token` string: Authentication token. Used in the `otp` authentication method.
      - `user_id` string: User ID. Used in the `otp` authentication method.
      - `hash` string: Value generated at the time of authentication via OTP and intended for authentication via signing. Used in the `transaction_signing` authentication method.
      - `signing_data` object: Object that contains authorization information provided at time of signing. Used in the `transaction_signing` authentication method.
  - `description` string: Optional text that describes the operation.
  - `metadata` Metadata: 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. The 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. **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](ref:get-started-with-pismo-apis#metadata).
  - `payment_datetime` string, date-time: Effective payment date in the UTC-0 RFC3339 format, which includes milliseconds (yyyy-MM-ddThh:mm:ss.SSSZ). Payments can be backdated but future dates are not allowed.
  - `pre_authorization` boolean: If set to `true`, this flag indicates that the operation is pre-authorized and requires additional confirmation.
  - `validation_rules` ValidationRules: Validation rules performed in the flow. Each key is a rule name (such as `ACCOUNT_STATUS` or `LEDGER`) and the value is its configuration.
  - `authorization_validations` AuthorizationValidations: 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.
    - `is_device_registered` boolean: Indicates whether the device used for the operation is registered according to the financial institution's security policies.
    - `associated_ids` AssociatedIDs: External IDs used in the authorization flow.
      - `payment_id` string: External ID associated with the authorization.
      - `origin_id` string: External ID of the origin of the authorization.
  - `original_authorization` OriginalAuthorization: This optional field identifies the original authorization to be linked. When this object is provided, both the `id` and `type` fields need to be filled.
    - `id` integer, required: Original authorization ID in the Pismo platform.
    - `type` 'NETWORK' | 'PLATFORM', required: Original authorization type.

## Response `200`

Request was processed successfully, existing authorization with the corresponding `tracking_id` returned.

- V2PaymentsResponse: Response for a cash-in or cash-out operation.
  - `amount` number, float, required: Credit or debit amount.
  - `authorization_id` integer, required: Unique Pismo-generated ID of the authorization created for this request. Returned on 200 and 201 responses, including idempotent replays.
  - `response_code` string, required: 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.
  - `tracking_id` string, required: Unique tracking ID for this operation.
  - `account_id` integer: Pismo account ID.
  - `denial_code` string: Denial code.
  - `validation_results` object[]
    - `name` string: Name of the evaluated rule.
    - `status` 'APPROVED' | 'REJECTED' | 'SKIPPED': Identifies if the rule was approved, rejected, or skipped during the validation flow.
    - `reason` string: Status reason why the specific rule was approved, rejected, or skipped.
    - `description` string: Description of the validation result.
    - `additional_data` object: Additional data for the validation result. This varies from validation to validation, but every denied validation has the `denial_code` and `response_code` fields.

## Other responses

- `201`: Request was processed successfully, new authorization created.
- `400`: Bad request
- `401`: Access token is missing or invalid.
- `409`: Conflict
- `422`: Unprocessable request
- `500`: Internal server error

---

[API](https://skmtc.dev/pismo/apis/core-platform-payment-methods.md) - [All operations](https://skmtc.dev/pismo/apis/core-platform-payment-methods/llms.txt) - [OpenAPI document](https://skmtc.dev/pismo/apis/core-platform-payment-methods/revisions/ab9e879a54e0?raw)