POST/api/validations

Validation

Create a validation request: msv-service sends the user a message through the channels you specify, with a link to approve or reject.

The 201 response only confirms that the request was created and the messages were sent; the status is always PENDING. The user's response arrives later via webhook, or you can check it with the token in Validation Query.

Request

  • Name
    locale
    Type
    string
    is optional
    Description

    Defines the language to use in ISO 639-1 format

    Allowed values:esenptit
    Example:es
    Max length:2
    Min length:2
  • Name
    reference
    Type
    string
    is Required
    REQUIRED
    Description

    Identifier of the item to validate

    Example:ref-12548
    Max length:50
  • Name
    message
    Type
    string
    is Required
    REQUIRED
    Description

    Message displayed in the email and in the approval view.

  • Name
    kind
    Type
    string
    is optional
    Description

    Field used to classify a request

    Example:Horus
    Max length:50
  • Name
    webhook_url
    Type
    string
    is Required
    REQUIRED
    Description

    URL of your server where msv-service will send the result via POST when the user responds or when the request expires.

    Example:https://example-url.com/
    Max length:255
  • Name
    minutes_by_expire
    Type
    integer
    is optional
    Description

    Minutes the user has to respond. When expired, the request changes to PARTIAL_EXPIRED and the webhook is sent with that status (minimum 1, maximum 60).

    Default value:30
    Example:20
  • Name
    buttons
    Type
    object
    is optional
    Description

    Structure that defines the text for the approval and rejection options

  • Name
    channels
    Type
    object
    is Required
    REQUIRED
    Description

    Structure required to define the channel details to use

Request

POST
/api/validations
curl -X "POST" {{baseURl}}/api/validations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "locale": "en",
    "reference": "ref-12548",
    "message": "Example Validation",
    "kind": "Horus",
    "webhook_url": "https://example-url.com/",
    "minutes_by_expire": 10,
    "buttons": {
      "approve": "accept",
      "reject": "reject"
    },
    "channels": {
      "sms": {
        "phone_number": "+573124567890",
        "short_message": "SMS Message"
      },
      "whatsapp": {
        "phone_number": "+573124567890",
        "template": {
          "name": "hello_world",
          "lang": "en_US",
          "parameters": [
            "name"
          ]
        }
      },
      "email": {
        "email": "[email protected]",
        "subject": "email subject"
      }
    }
  }'

Response

The validation request was created and the messages were sent.

  • Name
    status
    Type
    object
    is optional
    Description
  • Name
    reference
    Type
    string
    is optional
    Description

    Identifier of the item to validate

    Example:0122333444455555
  • Name
    token
    Type
    string
    is optional
    Description

    Request identifier (8 hexadecimal characters)

    Example:d5d67dcb
  • Name
    kind
    Type
    string
    is optional
    Description

    Request classification

    Example:horus

Response

POST
/api/validations
{
  "status": {
    "status": "PENDING",
    "reason": null,
    "message": "Transaction pending approval",
    "date": "2022-07-08T09:34:48-05:00"
  },
  "reference": "ref-12548",
  "token": "d5d67dcb",
  "kind": "Horus"
}

Important: a 400 response on /api/validations does not roll back an already created request. Channels that were already sent remain active, and the user may still approve or reject the request.