---
updatedAt: 2026-03-13T17:01:00.000Z
agentTools:
  projectIndex: https://developers.masspay.io/llms.txt
---

# Add new funding instrument

This **POST** endpoint is used to add a funding account instrument. <br> You can use this endpoint to provide the funding instrument details and add them to your account. <br> The request body requires the `funding_details` of the instrument, such as account and routing number or debit card details and the `country_code` of the country code where this funding instrument resides. <br> The response will include a JSON objects containing funding instrument `token`.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "description": "MassPay API",
    "version": "1.0.0",
    "title": "MassPay API",
    "termsOfService": "https://www.masspay.io/terms/",
    "contact": {
      "name": "MassPay",
      "email": "info@masspay.io",
      "url": "https://www.masspay.io"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "tags": [
    {
      "name": "Account",
      "description": "The account resource describes your account."
    }
  ],
  "paths": {
    "/payout/account/topup/instruments": {
      "post": {
        "tags": [
          "Account"
        ],
        "summary": "Add new funding instrument",
        "description": "This **POST** endpoint is used to add a funding account instrument. <br> You can use this endpoint to provide the funding instrument details and add them to your account. <br> The request body requires the `funding_details` of the instrument, such as account and routing number or debit card details and the `country_code` of the country code where this funding instrument resides. <br> The response will include a JSON objects containing funding instrument `token`.",
        "operationId": "postAddInstrument",
        "responses": {
          "200": {
            "description": "successful operation",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "x-examples": {
                    "Example 1": {
                      "token": ""
                    }
                  },
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "Token of newly created funding instrument",
                      "example": "fund_be2f0ab9-a503-473e-aa33-0af196e54647"
                    }
                  },
                  "required": [
                    "token"
                  ]
                },
                "examples": {
                  "Created funding instrument": {
                    "value": {
                      "token": "fund_be2f0ab9-a503-473e-aa33-0af196e54647"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error403"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error404"
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error405"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error500"
                }
              }
            }
          },
          "504": {
            "description": "Gateway Time-out.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error504"
                }
              }
            }
          }
        },
        "security": [
          {
            "AUTHORIZER_NAME": []
          },
          {
            "api_key": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "x-examples": {
                  "Example 1": {
                    "currency_code": "USD",
                    "type": "ACH",
                    "funding_details": {
                      "account_number": "",
                      "routing_number": "",
                      "debit_card_number": "",
                      "debit_card_expiration": "05/25",
                      "debit_card_billing_zip": ""
                    },
                    "country_code": "USA"
                  }
                },
                "properties": {
                  "funding_details": {
                    "type": "object",
                    "description": "Instrument details",
                    "properties": {
                      "account_number": {
                        "type": "string",
                        "description": "Bank account number. Required for ACH",
                        "example": "123456789"
                      },
                      "routing_number": {
                        "type": "string",
                        "description": "Bank routing number. Required for ACH",
                        "example": "021202337"
                      },
                      "bank_account_type": {
                        "type": "string",
                        "description": "Bank account type for ACH",
                        "enum": [
                          "Checking",
                          "Savings"
                        ],
                        "default": "Checking",
                        "example": "Checking"
                      },
                      "debit_card_number": {
                        "type": "string",
                        "description": "Debit card number. Required for AFT",
                        "example": "4457684565124683"
                      },
                      "debit_card_expiration": {
                        "type": "string",
                        "description": "Debit card expiration date. Format: `MM/YY`. Required for AFT",
                        "example": "05/35"
                      },
                      "debit_card_billing_zip": {
                        "type": "string",
                        "description": "Debit card billing zip code",
                        "example": "91304"
                      }
                    }
                  },
                  "country_code": {
                    "type": "string",
                    "description": "3 letter country code of institution where instrument exists",
                    "example": "USA"
                  }
                },
                "required": [
                  "funding_details",
                  "country_code"
                ]
              },
              "examples": {}
            }
          },
          "description": ""
        }
      },
      "parameters": []
    }
  },
  "servers": [
    {
      "url": "https://{environment}.masspay.io/{VERSION}",
      "description": "MassPay's API server",
      "variables": {
        "VERSION": {
          "default": "v1.0.0",
          "enum": [
            "v1.0.0"
          ]
        },
        "environment": {
          "default": "api",
          "enum": [
            "api",
            "staging-api"
          ]
        }
      }
    }
  ],
  "components": {
    "schemas": {
      "Error400": {
        "description": "Bad request.",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "title": {
            "type": "string",
            "description": "Error title.",
            "enum": [
              "Bad request."
            ],
            "example": "Bad request."
          },
          "message": {
            "type": "string",
            "description": "Error description.",
            "enum": [
              "The request was invalid or malformed. Please ensure that the request body conforms to the required format and that all required parameters are included."
            ],
            "example": "The request was invalid or malformed. Please ensure that the request body conforms to the required format and that all required parameters are included."
          },
          "code": {
            "type": "integer",
            "description": "Error code.",
            "enum": [
              400
            ],
            "example": 400
          },
          "error": {
            "type": "object",
            "properties": {
              "reason": {
                "type": "string",
                "example": "Error initiating payout",
                "description": "Reason for error"
              },
              "details": {
                "type": "array",
                "description": "Specific details of the cause of the error",
                "items": {
                  "type": "string",
                  "example": "Source amount cannot be $0"
                }
              }
            }
          }
        },
        "required": [
          "message",
          "code"
        ]
      },
      "Error401": {
        "description": "Unauthorized.",
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Error title.",
            "enum": [
              "Unauthorized."
            ],
            "example": "Unauthorized."
          },
          "message": {
            "type": "string",
            "description": "Error description.",
            "enum": [
              "Authentication failed or credentials were not provided. Please ensure that you have provided valid API credentials and that they are authorized to access the MassPay API."
            ],
            "example": "Authentication failed or credentials were not provided. Please ensure that you have provided valid API credentials and that they are authorized to access the MassPay API."
          },
          "code": {
            "type": "integer",
            "description": "Error code.",
            "enum": [
              401
            ],
            "example": 401
          }
        },
        "additionalProperties": false,
        "required": [
          "error",
          "message",
          "code"
        ]
      },
      "Error403": {
        "description": "Forbidden.",
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Error title.",
            "enum": [
              "Forbidden."
            ],
            "example": "Forbidden."
          },
          "message": {
            "type": "string",
            "description": "Error description.",
            "enum": [
              "The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action."
            ],
            "example": "The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action."
          },
          "code": {
            "type": "integer",
            "description": "Error code.",
            "enum": [
              403
            ],
            "example": 403
          }
        },
        "additionalProperties": false,
        "required": [
          "error",
          "message",
          "code"
        ]
      },
      "Error404": {
        "description": "Not found.",
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Error title.",
            "enum": [
              "Not found."
            ],
            "example": "Not found."
          },
          "message": {
            "type": "string",
            "description": "Error description.",
            "enum": [
              "The requested resource was not found. Please ensure that the URL for the request is correct and that the requested resource exists."
            ],
            "example": "The requested resource was not found. Please ensure that the URL for the request is correct and that the requested resource exists."
          },
          "code": {
            "type": "integer",
            "description": "Error code.",
            "enum": [
              404
            ],
            "example": 404
          }
        },
        "additionalProperties": false,
        "required": [
          "error",
          "message",
          "code"
        ]
      },
      "Error405": {
        "description": "Method not allowed.",
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Error title.",
            "enum": [
              "Method not allowed."
            ],
            "example": "Method not allowed."
          },
          "message": {
            "type": "string",
            "description": "Error description.",
            "enum": [
              "The HTTP method used for the request is not supported by the MassPay API. Please ensure that you are using the correct HTTP method (e.g., POST) for the specific MassPay API endpoint."
            ],
            "example": "The HTTP method used for the request is not supported by the MassPay API. Please ensure that you are using the correct HTTP method (e.g., POST) for the specific MassPay API endpoint."
          },
          "code": {
            "type": "integer",
            "description": "Error code.",
            "enum": [
              405
            ],
            "example": 405
          }
        },
        "additionalProperties": false,
        "required": [
          "error",
          "message",
          "code"
        ]
      },
      "Error500": {
        "description": "Internal server error",
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Error title.",
            "enum": [
              "Internal server error."
            ],
            "example": "Internal server error."
          },
          "message": {
            "type": "string",
            "description": "Error description.",
            "enum": [
              "An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists."
            ],
            "example": "An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists."
          },
          "code": {
            "type": "integer",
            "description": "Error code.",
            "enum": [
              500
            ],
            "example": 500
          }
        },
        "additionalProperties": false,
        "required": [
          "error",
          "message",
          "code"
        ]
      },
      "Error504": {
        "description": "Gateway Time-out.",
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Error title.",
            "enum": [
              "Gateway Time-out."
            ],
            "example": "Gateway Time-out."
          },
          "message": {
            "type": "string",
            "description": "Error description.",
            "enum": [
              "The request timed out while waiting for a response from the server. Please try again later or contact support if the issue persists."
            ],
            "example": "The request timed out while waiting for a response from the server. Please try again later or contact support if the issue persists."
          },
          "code": {
            "type": "integer",
            "description": "Error code.",
            "enum": [
              500
            ],
            "example": 500
          }
        },
        "additionalProperties": false,
        "required": [
          "error",
          "message",
          "code"
        ]
      }
    },
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header"
      },
      "AUTHORIZER_NAME": {
        "name": "Authorization",
        "in": "header",
        "type": "apiKey"
      }
    }
  }
}
```