Transaction · Standard API · eKYC Core

Create a transaction

POST/v1/transactions

Opens a new transaction and returns its transaction id and channel id.

Request

MethodPOST
Path/v1/transactions
Content-Typeapplication/json
Auth requiredYes — HMAC signing

Transaction-ID is the reconciliation mechanism recommended for the India market — see API Reconciliation.

NameTypeRequiredDescriptionSupported countries
reference_idstringOptionalreference id from clientall
channel_namestringOptionalchannel name from clientall
metadatadictionaryOptionalkey-value, key should be string, value should be string, int, float, boolall
agent_numberstringOptionalagent numberindia
agent_namestringOptionalagent nameindia
client_transaction_idstringOptionaltransaction id of clientindia
client_apk_version_numberstringOptionalapk version of clientindia
brand_identifierstringOptionalbrand identifierindia
customer_namestringOptionalcustomer nameindia
JSON
{
    "reference_id": string,
    "channel_name": string,
    "metadata": dictionary,
    "agent_number": string,
    "agent_name", string,
    "client_transaction_id", string,
    "client_apk_version_number", string,
    "brand_identifier", string,
}

Sample request

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/transactions \
-H 'Authorization: TV <YOUR ACCESS KEY>:<CREATED SIGNATURE>' \
-H 'X-TV-Timestamp: 2019-04-21T18:00:15+07:00' \
-H 'Content-Type: application/json' \
-d \
'
{
    "reference_id": "536d2457-bfc0-4249-85f2-8c4053bdec58"
}
'

Response

On success the HTTP status code is 200, and data carries id and channel_id. The errors array uses the shared response envelope.

JSON
{
    "data": {
        "id": uuid,
        "channel_id": uuid,
    },
    "errors": [
        {
            "code": string,
            "message": string,
            "detail": {
                "field": string, // optional, which parameter is invalid.
                ... // any other information that can be useful for client
            },
        },
        ... // other errors
    ]
}

A created transaction comes back like this:

JSON
{
    "data": {
        "id": "cfc7b8d5-f2e2-437b-80e5-d600dfad26e2",
        "channel_id": "416ab0e7-13a2-4b4b-9304-03bb8612d817"
    }
}

Failure codes

If the data.status is "failure", the "errors" field will tell you why it failed.

In case of any other errors, the data field will be empty, and the server sends one of following HTTP status code with error code:

HTTP codeError codeDescription
401access_denied_exceptionYou are not authorized to perform the action.
400invalid_parameter_exceptionInput parameter violates a constraint.
400request_time_too_skewedThe X-TV-Timestamp header is expired, need a newer one.
408request_timeout_exceptionRequest takes too long to process
429rate_limit_exceptionThe number of requests exceeded your throughput limit.
500internal_server_errorSome unexpected error occurs while processing the request

The codes above are the ones documented for this endpoint. Response errors on the Overview lists the codes for the eKYC Core surface as a whole — the two lists do not match on every endpoint.