Introduction
This document describes TotalCoin API endpoints to register payments from external systems.
Authentication
API access control is done through the standard OAuth 2.0 with Bearer Tokens.
Endpoint
POST
api/auth/login
Request
{
"company": "",
"username": "",
"password": ""
}
| Field | Type | Description | Required |
|---|---|---|---|
| company | String | Company Name | Yes |
| username | String | Username | Yes |
| password | String | Password | Yes |
Response (HTTP 200)
{
"token": "",
"expires_in": 3600
}
| Field | Type | Description |
|---|---|---|
| token | String | Authentication token |
| expires_in | Number | Token expiration in seconds |
Common Errors
| Code | Description |
|---|---|
| 401 | Invalid or wrong credentials |
| 403 | Not enough permissions to access the API |
Make a Payment
Make a payment transaction to a client's account.
Endpoint
POST
api/payments/transactions
Request
{
"cbucvu": "",
"cuitcuil": "",
"amount": 0,
"reference": "",
"notificationUrl": ""
}
| Field | Type | Description | Required |
|---|---|---|---|
| cbucvu | String | CBU / CVU number of payment recipient (22 Characters) | Yes |
| cuitcuil | String | CUIT / CUIL number of payment recipient (11 Characters) | Yes |
| amount | Number | Payment Amount | Yes |
| reference | String | Number or reference code from the system that sends the payment | Yes |
| notificationUrl | String | URL used to notify transaction results | Yes |
Response (HTTP 200)
{
"id": ""
}
| Field | Type | Description |
|---|---|---|
| id | String | ID of transaction received successfully |
Common Errors
| Code | Description |
|---|---|
| 400 | Invalid data to process transactions. Includes details of the validation |
| 401 | Unauthorized - cannot make the transaction |
| 409 | Duplicated. There's already a transaction with the same number or reference code |
| 500 | Error processing the transaction |
Result Notification (Callback)
Call to the endpoint informed in the Make a payment request. It contains the status of the processed transaction.
Headers
| Key | Value |
|---|---|
| Authorization | SHA256 Hash |
Body
{
"body": {
"id": "",
"status": ""
},
"securityKey": ""
}
| Field | Type | Description |
|---|---|---|
| body | Object | Object with transaction data |
| id | String | Transaction id |
| status | String | Description of the transaction current status |
| securityKey | String | Empty field to be filled with the provided private key |
CLARIFICATION ON STATUS REPORTED
In some cases, the reported status will not correspond to the final status, this is due to delays in the processing by BIND. For better details, the status might need to be checked against the endpoint Verify payment.
In some cases, the reported status will not correspond to the final status, this is due to delays in the processing by BIND. For better details, the status might need to be checked against the endpoint Verify payment.
Hash Calculation
Here are the steps to calculate a hash, sent in the Authorization Header:
- To the JSON received, add the private key provided by a secure channel to the securityKey field
- Convert received JSON object to lowercase
- Calculate the SHA256 hash
Example:
JSON received:
{"Body":{"Id":"E6451028-84CE-4FA4-B3BC-335972BEBF0A","Status":"Failed"},"Securitykey":""}
Private key: 09B4ET8C4EB24S8ABTA8B8A
JSON with SecurityKey field:
{"Body":{"Id":"E6451028-84CE-4FA4-B3BC-335972BEBF0A","Status":"Failed"},"Securitykey":"09B4ET8C4EB24S8ABTA8B8A"}
JSON converted to lowercase:
{"body":{"id":"e6451028-84ce-4fa4-b3bc-335972bebf0a","status":"failed"},"securitykey":"09b4et8c4eb24s8abta8b8a"}
Hash:
4e36de37b87010d301e4b3a9046befe24ef253a98746f1d43998f29c31e188d4
Verify Payment
Check the status of any particular payment.
Endpoint
GET
api/payments/transactions/{id}
Request
api/payments/transactions/00000000-0000-0000-0000-000000000000
| Field | Type | Description | Required |
|---|---|---|---|
| id | String | Id of transaction | Yes |
Response (HTTP 200)
{
id: "",
status: "",
amount: 0.00,
date: "",
reference: ""
}
| Field | Type | Description |
|---|---|---|
| id | String | Id of transaction received correctly |
| status | String | Details of the transaction current status |
| amount | decimal | Transaction amount |
| date | String | Transaction date |
| reference | String | Number or reference code of the system that generates the transaction |
Common Errors
| Code | Description |
|---|---|
| 400 | Invalid data to process the request |
| 401 | Unauthorized |
| 404 | Transaction not found |
| 500 | Error processing the request |
Transaction Statuses
| Status | Description |
|---|---|
| Processed | Transaction processed successfully. Final Status. |
| Failed | Rejected Transaction. Final Status. |
| Processing | Pending Transaction. Need to check again. |
| Pending | Transaction received and pending processing. Need to check again. |
Verify Payment by External Id
Check the status of any particular payment using an external identifier.
Endpoint
GET
api/payments/transactions/{id}/external
Request
api/payments/transactions/0000000/external
| Field | Type | Description | Required |
|---|---|---|---|
| id | String | Id of transaction | Yes |
Response (HTTP 200)
{
id: "",
status: "",
amount: 0.00,
date: "",
reference: ""
}
| Field | Type | Description |
|---|---|---|
| id | String | Id of transaction received correctly |
| status | String | Details of the transaction current status |
| amount | decimal | Transaction amount |
| date | String | Transaction date |
| reference | String | Number or reference code of the system that generates the transaction |
Common Errors
| Code | Description |
|---|---|
| 400 | Invalid data to process the request |
| 401 | Unauthorized |
| 404 | Transaction not found |
| 500 | Error processing the request |