---
updatedAt: 2026-04-29T07:02:30.000Z
agentTools:
  projectIndex: https://developers.muralpay.com/llms.txt
---

# Simulate a payin

Triggers a simulated inbound payin on a sandbox deposit account. Useful for testing payin receipt flows without initiating a real bank transfer. Only available in sandbox environments.

# OpenAPI definition

```json
{
  "components": {
    "schemas": {
      "AchPayinAmount": {
        "properties": {
          "currencySymbol": {
            "enum": [
              "USD"
            ],
            "type": "string"
          },
          "value": {
            "description": "The amount in cents (e.g., \"2500\" represents 25.00). Must not exceed 50 USD.",
            "example": "2500",
            "type": "string"
          }
        },
        "required": [
          "value",
          "currencySymbol"
        ],
        "type": "object"
      },
      "AchPayinRail": {
        "properties": {
          "amount": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AchPayinAmount"
              }
            ],
            "description": "The amount to simulate. Must be denominated in USD."
          },
          "type": {
            "enum": [
              "ach"
            ],
            "type": "string"
          }
        },
        "required": [
          "type",
          "amount"
        ],
        "type": "object"
      },
      "CvuPayinAmount": {
        "properties": {
          "currencySymbol": {
            "enum": [
              "ARS"
            ],
            "type": "string"
          },
          "value": {
            "description": "The amount in cents (e.g., \"2500\" represents 25.00). Must not exceed 65,000 ARS.",
            "example": "2500",
            "type": "string"
          }
        },
        "required": [
          "value",
          "currencySymbol"
        ],
        "type": "object"
      },
      "CvuPayinRail": {
        "properties": {
          "amount": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CvuPayinAmount"
              }
            ],
            "description": "The amount to simulate. Must be denominated in ARS."
          },
          "type": {
            "enum": [
              "cvu"
            ],
            "type": "string"
          }
        },
        "required": [
          "type",
          "amount"
        ],
        "type": "object"
      },
      "PixPayinAmount": {
        "properties": {
          "currencySymbol": {
            "enum": [
              "BRL"
            ],
            "type": "string"
          },
          "value": {
            "description": "The amount in cents (e.g., \"2500\" represents 25.00). Must not exceed 275 BRL.",
            "example": "2500",
            "type": "string"
          }
        },
        "required": [
          "value",
          "currencySymbol"
        ],
        "type": "object"
      },
      "PixPayinRail": {
        "properties": {
          "amount": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PixPayinAmount"
              }
            ],
            "description": "The amount to simulate. Must be denominated in BRL."
          },
          "type": {
            "enum": [
              "pix"
            ],
            "type": "string"
          }
        },
        "required": [
          "type",
          "amount"
        ],
        "type": "object"
      },
      "RateLimitExceededErrorBody": {
        "properties": {
          "errorInstanceId": {
            "description": "Unique error instance ID",
            "format": "uuid",
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "name": {
            "example": "RateLimitExceededError",
            "type": "string"
          },
          "params": {
            "$ref": "#/components/schemas/RateLimitExceededErrorBodyParams"
          }
        },
        "required": [
          "errorInstanceId",
          "name",
          "message",
          "params"
        ],
        "type": "object"
      },
      "RateLimitExceededErrorBodyParams": {
        "properties": {
          "retryAfterSeconds": {
            "description": "Seconds to wait before retrying. The same value is sent in the Retry-After header.",
            "type": "number"
          }
        },
        "required": [
          "retryAfterSeconds"
        ],
        "type": "object"
      },
      "SignedAgreementRequiredErrorBodyParams": {
        "properties": {
          "organizationId": {
            "description": "Organization ID that must accept the agreement",
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "organizationId"
        ],
        "type": "object"
      },
      "SignedAgreementRequiredExceptionBody": {
        "properties": {
          "errorInstanceId": {
            "description": "Unique error instance ID",
            "format": "uuid",
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "name": {
            "example": "SignedAgreementRequiredException",
            "type": "string"
          },
          "params": {
            "$ref": "#/components/schemas/SignedAgreementRequiredErrorBodyParams"
          }
        },
        "required": [
          "errorInstanceId",
          "name",
          "message",
          "params"
        ],
        "type": "object"
      },
      "SimulateSandboxPayinRequest": {
        "properties": {
          "destinationAccountId": {
            "description": "The ID of the payin deposit account that will receive the simulated inbound transfer.",
            "example": "b4f3c1d2-89ab-4e56-8f01-23456789abcd",
            "format": "uuid",
            "type": "string"
          },
          "rail": {
            "description": "The payment rail and amount for the simulated payin. Use the `type` discriminator to select the rail; each rail enforces a fixed currency (SPEI → MXN, PIX → BRL, CVU → ARS, ACH/WIRE → USD).",
            "oneOf": [
              {
                "$ref": "#/components/schemas/SpeiPayinRail",
                "title": "SPEI"
              },
              {
                "$ref": "#/components/schemas/PixPayinRail",
                "title": "PIX"
              },
              {
                "$ref": "#/components/schemas/CvuPayinRail",
                "title": "CVU"
              },
              {
                "$ref": "#/components/schemas/AchPayinRail",
                "title": "ACH"
              },
              {
                "$ref": "#/components/schemas/WirePayinRail",
                "title": "WIRE"
              }
            ]
          }
        },
        "required": [
          "destinationAccountId",
          "rail"
        ],
        "type": "object"
      },
      "SpeiPayinAmount": {
        "properties": {
          "currencySymbol": {
            "enum": [
              "MXN"
            ],
            "type": "string"
          },
          "value": {
            "description": "The amount in cents (e.g., \"2500\" represents 25.00). Must not exceed 1,000 MXN.",
            "example": "2500",
            "type": "string"
          }
        },
        "required": [
          "value",
          "currencySymbol"
        ],
        "type": "object"
      },
      "SpeiPayinRail": {
        "properties": {
          "amount": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SpeiPayinAmount"
              }
            ],
            "description": "The amount to simulate. Must be denominated in MXN."
          },
          "type": {
            "enum": [
              "spei"
            ],
            "type": "string"
          }
        },
        "required": [
          "type",
          "amount"
        ],
        "type": "object"
      },
      "WirePayinAmount": {
        "properties": {
          "currencySymbol": {
            "enum": [
              "USD"
            ],
            "type": "string"
          },
          "value": {
            "description": "The amount in cents (e.g., \"2500\" represents 25.00). Must not exceed 50 USD.",
            "example": "2500",
            "type": "string"
          }
        },
        "required": [
          "value",
          "currencySymbol"
        ],
        "type": "object"
      },
      "WirePayinRail": {
        "properties": {
          "amount": {
            "allOf": [
              {
                "$ref": "#/components/schemas/WirePayinAmount"
              }
            ],
            "description": "The amount to simulate. Must be denominated in USD."
          },
          "type": {
            "enum": [
              "wire"
            ],
            "type": "string"
          }
        },
        "required": [
          "type",
          "amount"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "bearer": {
        "bearerFormat": "API key",
        "description": "Your API key from the Developers page, for example `mural_live_<64 hex characters>`. Send it as `Authorization: Bearer <API key>`. The Transfer API key goes in the `transfer-api-key` header, never here.",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "contact": {},
    "description": "Mural's API for programmatic global payments.",
    "title": "Mural API",
    "version": "1.0"
  },
  "openapi": "3.0.0",
  "paths": {
    "/api/sandbox/simulate/payin": {
      "post": {
        "description": "Triggers a simulated inbound payin on a sandbox deposit account. Useful for testing payin receipt flows without initiating a real bank transfer. Only available in sandbox environments.",
        "operationId": "simulatePayin",
        "parameters": [
          {
            "description": "Organization ID to act on behalf of",
            "in": "header",
            "name": "on-behalf-of",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SimulateSandboxPayinRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "The simulated payin was successfully initiated."
          },
          "400": {
            "description": "The amount exceeds the sandbox cap for the rail, or the rail is not supported for this deposit account."
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignedAgreementRequiredExceptionBody"
                }
              }
            },
            "description": "SignedAgreementRequiredException"
          },
          "404": {
            "description": "No deposit account was found for the provided `destinationAccountId`, or the account does not belong to the calling organization."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitExceededErrorBody"
                }
              }
            },
            "description": "RateLimitExceededError"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Simulate a payin",
        "tags": [
          "Sandbox"
        ]
      }
    }
  },
  "servers": [
    {
      "description": "Production",
      "url": "https://api.muralpay.com"
    },
    {
      "description": "Sandbox",
      "url": "https://api-staging.muralpay.com"
    }
  ]
}
```