Request PIN/OTP (One-Time Password)
Description
To request for a PIN/OTP (one-time password), it is necessary to make a POST request to the Confirm API endpoint.
Production Endpoint URL: https://api.cpaas.symphony.rakuten.net/twofa/v1/request
Methods: POST
HTTP Headers
| Parameter | Required | Value |
|---|---|---|
| Authentication | Y | Type: Bearer Token: JWT Token |
| Accept | Y | application/json |
| Content-Type | Y | application/json; charset=UTF-8 |
Request Body Schema: application/json
| Parameter | Required | Description/Values |
|---|---|---|
| to | Y | The destination phone number should be in the format: Country Code + Mobile Number (MSISDN)
|
| language | Y | See section Supported Languages Example ENGLISH: en_GB or en_gb JAPANESE: ja_JP or ja_jp |
| outcome_url | Y | This is the callback URL which will be used in the future. Pass any dummy value. |
| from | Conditional | This can be either a Sender ID or Number depending on requirement and configuration.[This value should be specified if the default sender address is not whitelisted.] Sender addresses must be registered with the operators. Please ask your account manager to register your sender addresses. SMS will not reach the subscribers handset if sender addresses are not registered correctly. All correctly registered sender addresses will be shown on the user dashboard |
| api_key | Optional | This is the API Key used during authentication and can be passed for reference |
| charge_profile | Optional | The following charging profiles are available: PAY_PER_REQUEST: Charge a flat fee for a request, regardless of the outcome, all message costs are included in this fee. PAY_PER_CONVERSION: Charge a flat fee for a request, but only charge if the request is successfully confirmed with a PIN, all message costs are included in this fee. PAY_FOR_MESSAGES_PLUS_SERVICE_FEE: Charge a service fee for a request, regardless of the outcome, in addition to any message fees for any calls or messages placed by this request. PAY_FOR_MESSAGES_PLUS_CONVERSION_FEE: Charge a service fee for a request that successfully confirms with a PIN, in addition to any message fees for any calls or messages placed by this request. Default Charge Profile: PAY_FOR_MESSAGES_PLUS_CONVERSION_FEE |
| customization | Optional | The following parameters can be used to customize the PIN request |
| ┗pin_length | Default: 6 Min: 3 Max: 8 | |
| ┗message_text | Customized message to be sent to customer e.g., Your pin code is: ${pin} | |
| ┗workflow | Currently only SMS workflow is supported Default: sms | |
| metadata | Optional | Additional metadata for tracking |
| ┗client_reference | Enterprise can send a client reference value to track the request e.g., client-ref-1 | |
| ┗company_name | The company name of the Enterprise for reference |
Sample Request
{
"to": "81XXXXXXXXXX",
"outcome_url": "http://www.example.com",
"language": "en_GB",
"from": "81YYYYYYYYYY",
//These are optional parameters
"customization": {
"pin_length": "8",
"message_text": "Your pin code is: ${pin}",
"workflow": "sms",
}
//These are optional parameters
"metadata": {
"client_reference": "client-ref-1",
"company_name": “...Company ABC...",
}
}
Response:
If successful, the API call will return an HTTP 200 OK with a JSON document as a response. Please see section "Errors/Rejections of Submit SMS API Request" for a description of the failure responses.
| Parameter | Description |
|---|---|
| result_code | Refer Result Code List |
| result_message | Description of the result code |
| client_reference | Client reference is returned only when specified in request. Information on attaching "client reference" can be found under "Additional/Advanced Options". |
| request_id | Auto-generated Id |
Sample Response
{
"success": true,
"result_code" : 0,
"result_message" : "Request successfully submitted",
"request_id" : "...auto-generated id...",
"client_reference": "...if provided during original request..."
}