---
updatedAt: 2026-08-25T13:51:23.000Z
agentTools:
projectIndex: https://developers.masspay.io/llms.txt
---
# Store user attributes
This **POST** endpoint is used to store user attributes, allowing you to associate additional data with a user token.
To use this endpoint, you need to provide the `user_token`, `endpoint_token`, and `currency` as parameters in the URL Path. You also need to provide the attribute values as JSON parameters in the Request body.
If existing attributes are already stored for the user, this call will create a new `attr_set_token`.
When the attribute type is `SocialSecurity` or `EIN`, the transaction is allowed to proceed while the number and name are validated against IRS records in the background. The result of this validation is delivered via a webhook under the `kyc.tax` event.
If the SSN or EIN does not match the name on file with the IRS, the user will be prompted to re-enter it the next time they attempt to initiate a transaction. At that point, the user should update either their name or their SSN/EIN.
# 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"
}
},
"x-amazon-apigateway-api-key-source": "AUTHORIZER",
"tags": [
{
"name": "Attribute",
"description": "The attribute resource describes attributes of a user. For instance their bank account number, ID number, DOB, etc."
}
],
"paths": {
"/attribute/{user_token}/{endpoint_token}/{currency}": {
"post": {
"tags": [
"Attribute"
],
"summary": "Store user attributes",
"description": "This **POST** endpoint is used to store user attributes, allowing you to associate additional data with a user token.
To use this endpoint, you need to provide the `user_token`, `endpoint_token`, and `currency` as parameters in the URL Path. You also need to provide the attribute values as JSON parameters in the Request body.
If existing attributes are already stored for the user, this call will override their values.",
"operationId": "storeAttrs",
"parameters": [
{
"name": "user_token",
"in": "path",
"description": "Token representing the user to store attributes for",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "endpoint_token",
"in": "path",
"description": "Token representing the transaction endpoint — either the `destination_token` for payouts (e.g., MassPay → Brazil → Bank Deposit → Itau), or the `origin_token` for pay-ins. For payouts, this value is retrieved from the [country services](/reference/getbestcountryservices) endpoint.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Unique key to prevent duplicate processing",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AttrTxn"
},
"examples": {
"Store attributes": {
"value": {
"values": [
{
"token": "e2ca24e9-c546-4c64-90d2-cb8e70e7c9ba",
"value": "432532532"
}
],
"attr_set_token": "attr_set_e2ca24e9-c546-4c64-90d2-cb8e70e7c9ba",
"label": "JPMorgan Chase"
}
}
}
}
},
"description": "Attr parameters to store",
"required": true
},
"responses": {
"201": {
"description": "Succesfully created.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"attr_set_token": {
"type": "string",
"description": "`attr_set_token` associated with the stored attributes"
}
},
"required": [
"attr_set_token"
]
},
"examples": {
"Successful storing of attributes": {
"value": {
"attr_set_token": "attr_set_87e7599d-af96-4aec-9097-c2a105bc2d64"
}
}
}
}
}
},
"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": []
}
],
"x-amazon-apigateway-integration": {
"uri": "LAMBDA_URI",
"responses": {
"default": {
"statusCode": "200"
}
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"contentHandling": "CONVERT_TO_TEXT",
"type": "aws_proxy"
},
"x-stoplight": {
"id": "ximirgywmzpw6"
}
},
"parameters": [
{
"schema": {
"type": "string",
"example": "usr_585ebb5b-e928-477d-9244-fb6af8f8dadb"
},
"name": "user_token",
"in": "path",
"required": true,
"description": "Token representing the user to store attributes for"
},
{
"schema": {
"type": "string",
"example": "BRL",
"minLength": 3,
"pattern": "^[A-Z0-9]{3,5}$",
"maxLength": 5
},
"name": "currency",
"in": "path",
"description": "The destination currency sending funds to. Using [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. ",
"required": true
},
{
"schema": {
"type": "string"
},
"name": "endpoint_token",
"in": "path",
"required": true,
"description": "Token representing the transaction endpoint — either the `destination_token` for payouts (e.g., MassPay → Brazil → Bank Deposit → Itau), or the `origin_token` for pay-ins. For payouts, this value is retrieved from the [country services](/reference/getbestcountryservices) endpoint."
}
]
}
},
"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"
]
}
},
"x-amazon-apigateway-endpoint-configuration": {
"disableExecuteApiEndpoint": true
}
}
],
"components": {
"schemas": {
"AttrTxn": {
"type": "object",
"xml": {
"name": "AttrTxn"
},
"x-examples": {
"AttrTxn": {
"values": [
{
"token": "e2ca24e9-c546-4c64-90d2-cb8e70e7c9ba",
"value": "432532532"
}
],
"attr_set_token": "e2ca24e9-c546-4c64-90d2-cb8e70e7c9ba",
"label": "JPM Chase"
}
},
"x-tags": [
"Attribute"
],
"required": [
"values"
],
"properties": {
"values": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AttrValue"
}
},
"attr_set_token": {
"type": "string",
"example": "attr_set_e2ca24e9-c546-4c64-90d2-cb8e70e7c9ba",
"description": "The token that represents a set of attributes for a specific payer. Optional, specify the value if you're trying to add a value for a specific attributes set. If the existing values associated with the attr_set_token are different, this value will be ignored and a new attr_set_token would be issued."
},
"label": {
"type": "string",
"description": "Optional user-defined label for identifying or naming this set of attributes. Useful for UI display or future reference.",
"maxLength": 100,
"example": "JPMorgan Chase"
}
}
},
"AttrValue": {
"type": "object",
"required": [
"token",
"value"
],
"properties": {
"token": {
"type": "string",
"example": "e2ca24e9-c546-4c64-90d2-cb8e70e7c9ba",
"description": "The token that represents the attribute that needs to be updated."
},
"value": {
"type": "string",
"example": "432532532",
"description": "The value that needs to be stored for the associated token"
}
},
"xml": {
"name": "AttrValue"
},
"x-examples": {
"AttrValue": {
"token": "attr_e2ca24e9-c546-4c64-90d2-cb8e70e7c9ba",
"value": "432532532"
}
},
"x-tags": [
"Attribute"
]
},
"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",
"x-internal": true
},
"AUTHORIZER_NAME": {
"x-amazon-apigateway-authtype": "custom",
"x-amazon-apigateway-authorizer": {
"authorizerUri": "AUTHORIZER_VALIDATION_INVOKE_ARN",
"authorizerCredentials": "AUTHORIZER_VALIDATION_ROLE",
"authorizerResultTtlInSeconds": 300,
"identityValidationExpression": "AUTHORIZER_VALIDATION_EXP",
"type": "token"
},
"name": "Authorization",
"in": "header",
"type": "apiKey"
}
}
},
"x-amazon-apigateway-gateway-responses": {
"AUTHORIZER_FAILURE": {
"statusCode": 500,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Internal server error.\",\n \"message\": \"An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists.\",\n \"code\": 500\n}"
}
},
"MISSING_AUTHENTICATION_TOKEN": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"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.\",\n \"code\": 403\n}"
}
},
"EXPIRED_TOKEN": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"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.\",\n \"code\": 403\n}"
}
},
"REQUEST_TOO_LARGE": {
"statusCode": 413,
"responseTemplates": {
"application/json": "{ \"title\": \"Unauthorized.\", \"message\": $context.error.messageString, \"code\": 413 }"
}
},
"ACCESS_DENIED": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"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.\",\n \"code\": 403\n}"
}
},
"INVALID_API_KEY": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"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.\",\n \"code\": 403\n}"
}
},
"QUOTA_EXCEEDED": {
"statusCode": 429,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Unauthorized.\",\n \"message\": $context.error.messageString,\n \"code\": 429\n}"
}
},
"INVALID_SIGNATURE": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"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.\",\n \"code\": 403\n}"
}
},
"DEFAULT_4XX": {
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Bad request.\",\n \"message\": $context.error.messageString,\n \"code\": 400\n}"
}
},
"THROTTLED": {
"statusCode": 429,
"responseTemplates": {
"application/json": "{ \"title\": \"Unauthorized.\", \"message\": $context.error.messageString, \"code\": 429 }"
}
},
"BAD_REQUEST_PARAMETERS": {
"statusCode": 400,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Bad request.\",\n \"message\": \"The request was invalid or malformed. Please ensure that the request body conforms to the required format and that all required parameters are included.\",\n \"code\": 400\n}"
}
},
"API_CONFIGURATION_ERROR": {
"statusCode": 500,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Internal server error.\",\n \"message\": \"An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists.\",\n \"code\": 500\n}"
}
},
"AUTHORIZER_CONFIGURATION_ERROR": {
"statusCode": 500,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Internal server error.\",\n \"message\": \"An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists.\",\n \"code\": 500\n}"
}
},
"INTEGRATION_TIMEOUT": {
"statusCode": 504,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Gateway Time-out.\",\n \"message\": \"The request timed out while waiting for a response from the server. Please try again later or contact support if the issue persists.\",\n \"code\": 504\n}"
}
},
"BAD_REQUEST_BODY": {
"statusCode": 400,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Bad request.\",\n \"message\": \"The request was invalid or malformed. Please ensure that the request body conforms to the required format and that all required parameters are included.\",\n \"code\": 400\n}"
}
},
"INTEGRATION_FAILURE": {
"statusCode": 504,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Gateway Time-out.\",\n \"message\": \"The request timed out while waiting for a response from the server. Please try again later or contact support if the issue persists.\",\n \"code\": 504\n}"
}
},
"DEFAULT_5XX": {
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Internal server error.\",\n \"message\": $context.error.messageString,\n \"code\": 500\n}"
}
},
"RESOURCE_NOT_FOUND": {
"statusCode": 404,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{ \"title\": \"Unauthorized.\", \"message\": $context.error.messageString, \"code\": 404 }"
}
},
"UNAUTHORIZED": {
"statusCode": 401,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Unauthorized.\",\n \"message\": \"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.\",\n \"code\": 401\n}"
}
},
"UNSUPPORTED_MEDIA_TYPE": {
"statusCode": 415,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{ \"title\": \"Unauthorized.\", \"message\": $context.error.messageString, \"code\": 415 }"
}
},
"WAF_FILTERED": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"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.\",\n \"code\": 403\n}"
}
}
},
"x-amazon-apigateway-minimum-compression-size": 1024
}
```