Placetopay Docs

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 confirms that the request was created and at least one channel delivered the message; the status is PENDING. If no channel delivered it, the response is 400 and the request is set to FAILED. In both cases, channels shows the result of each channel (see Channel results). 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 at least one channel delivered the message.

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
Name
channels
Type
array
is optional
Description
Delivery result per channel, in the same order the channels were sent in the request.

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",
  "channels": [
    {
      "channel": "sms",
      "delivered": true
    },
    {
      "channel": "whatsapp",
      "delivered": false,
      "reason": "template_rejected",
      "message": "The message template was rejected"
    },
    {
      "channel": "email",
      "delivered": true
    }
  ]
}

A 400 response on /api/validations means no channel confirmed delivery: the request is set to FAILED and no webhook is sent. If any channel returned delivery_unconfirmed, the message may still have reached the user, so check with Validation Query before taking any action.