Introduction

Welcome to the Guita API. This API allows merchant applications or services to request a payment from a client (Guita wallet) using the mobile phone number registered as identifier.

This API was specifically designed to facilitate "CASH IN" transactions for merchants exclusively.

This API documentation is maintained by the Guita Team - dev@guita.co.ao

Format

The format used to communicate with Guita API is through JSON requests and all the requests header should have a Content Type and Accept headers and have a valid JSON body (if required).

Content-Type: application/json

Accept: application/json

JSON body: The data within the payload fields should be in string format.

Timing

This timing specification is intended exclusively for the production environment.

New Payment Authorization: OTP timing

New Payment Confirmation: 10 minutes to confirm using the OTP PIN

New Refund: Adicional 10 minutes to Refund after Confirmation

Explanation:

The expiration time for Authorization request is 10 minutes, meaning that once the client receives the OTP, there is a 10-minute window to Confirm the payment. After the client confirms the payment to the merchant's account, there is also a 10-minute limit to initiate a Refund for the received amounts.

Environment

We're currently supporting production and sandbox environment to easily integrate using the same endpoint hostname. To determine the system if is either production or sandbox we use a unique token created at merchant portal for the specified system environment.

Authentication

To be able to use the Guita API you need to authenticate your requests through a bearer token in the Authorization header.

Authorization: Bearer [bearer_token]

Transaction Lifecycle

TRANSACTIONS

New Payment - Authorization

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0" \
  "https://external.api.guita.co.ao/v1/transactions" \
  -d '{"service": "wallet", "type": "authorization", "mobile": "912123123", "amount": "120048",
  callback_url: "https://your-hostname/link/to/confirm"}'

The above command returns a structure like this:

HTTP/1.1 202 Accepted
location: /v1/requests/b82b1dc4-f22b-48f5-90d8-c01c62339ebf

This resource endpoint allows to create a new payment authorization transaction.

HTTP Request

POST https://external.api.guita.co.ao/v1/transactions

Payload

Responses

New Payment - Confirmation

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0" \
  "https://external.api.guita.co.ao/v1/transactions" \
  -d '{"service": "wallet", "type": "confirmation", "otp": "123456", "parent_transaction_id": "b82b1dc4-f22b-48f5-90d8-c01c62339ebf", callback_url: "https://your-hostname/link/to/confirm"}'

The above command returns a structure like this:

HTTP/1.1 202 Accepted
location: /v1/requests/07f40cd7-9744-4c31-bfbc-c634ab53645f

This resource endpoint allows to create a new payment confirmation transaction.

HTTP Request

POST https://external.api.guita.co.ao/v1/transactions

Payload

Responses

New Refund

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0" \
  "https://external.api.guita.co.ao/v1/transactions" \
  -d '{service: "wallet", "type": "refund", "parent_transaction_id": "07f40cd7-9744-4c31-bfbc-c634ab53645f",
  callback_url: "https://your-hostname/link/to/confirm"}'

The above command returns a structure like this:

HTTP/1.1 202 Accepted
location: /v1/requests/bfbc1dc4-f22b-48f5-4c31-c01c62339ebf

This resource endpoint allows to create a new refund transaction.

HTTP Request

POST https://external.api.guita.co.ao/v1/transactions

Payload

Responses

Request

curl "https://external.api.guita.co.ao/v1/requests/90fa3a8a-2895-4d37-ab4b-7afd90de375a" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0"

The above command returns a structure like this:

HTTP/1.1 200 OK
Exemplar of Success
{
    "id": "d02969b0-d3f9-ab4b-2895-7afd90de375a ",
    "type": "confirmation",
    "service": "wallet",
    "parent_transaction_id": "e255c4c3-d8f7-4bd9-82e1-758fcf238656",
    "mobile": "912123123",
    "amount": "1.43",
    "status": "accepted",
    "status_reason": 'GT_2000',
    "status_datetime": "2024-01-23T13:00:25.771Z"
}

Exemplar of Failure
{
    "id": "90fa3a8a-87c2-4d37-d3f9-3f7773197599",
    "type": "authorization",
    "service": "wallet",
    "parent_transaction_id": null,
    "mobile": "912123123",
    "amount": "1.43",
    "status": "rejected",
    "status_reason": "GT_9000",
    "status_datetime": "2024-01-23T15:06:10.918Z"
}

This resource endpoint allows to verify the status of authorization, confirmation as well as refund transactions.

HTTP Request

GET https://external.api.guita.co.ao/v1/requests/{uuid}

Responses

Sandbox

All the structures and payloads explained above are identical for both the production and sandbox environments. To properly utilize the Sandbox environment, please adhere to the instructions below:

• Generate a Sandbox Environment Token on the Merchant Portal by creating an account.
• In the NIF validation section, it is essential to use the name returned on the AGT portal Consultar NIF.
• Utilize the generated token for authentication during your API requests.
• Utilize the provided Sandbox OTP PIN presented below to conduct the same tests.

Important Note: Ensure to anticipate and address all expected errors in the production environment.

• After completing the integration process in the sandbox environment, we kindly request that you contact the Guita sales team to formalize the use of the solution, enabling the transition to the production environment.

ERRORS

Transaction Codes

HTTP/1.1 200 OK 
These attributes constitute components of the payload included in the response 
body of "Request" call

{
    "id": "d02969b0-9744-42ab-87c2-c634ab53645f",
    "type": "authorization",
    "service": "wallet",
    "parent_transaction_id": "07f40cd7-9744-4c31-bfbc-c634ab53645f",
    "mobile": "912123123",
    "amount": "1.43",
    "status": "accepted",
    "status_reason": "GT_2000",
    "status_datetime": "2024-01-23T13:00:25.771Z"
}

OR

{
    "id": "d02969b0-9744-42ab-87c2-c634ab53645f",
    "type": "confirmation",
    "service": "wallet",
    "parent_transaction_id": "07f40cd7-9744-4c31-bfbc-c634ab53645f",
    "mobile": "912123123",
    "amount": "1.43",
    "status": "rejected",
    "status_reason": "GT_9000",
    "status_datetime": "2024-01-23T13:00:25.771Z"
}

In case of error while using the Guita API these are the ones we've documented for you:

HTTP/1.1 200 OK 
These attributes constitute components of the payload included in the response 
body of "Request" call

{
    "status": "accepted",
    "status_reason": null,
}

OR

{
    "status": "rejected",
    "status_reason": "19",
}

TESTING

SANDBOX OTP

The One-Time Password (OTP) utilized in the transaction confirmation tests will play a decisive role in determining the outcome of the transaction. The following are the scenarios effectively managed by the sandbox.

Kindly consult the error table for more accurate reference by utilizing the Status Reason.