NAV
cURL Java Javascript PHP Ruby Python C#

Introduction

Welcome to the Positiva GPO API. This gateway allows merchant applications or services to request a payment from a client, via Multicaixa Express (GPO), using the mobile phone number.

We have language bindings for Java, Javascript, PHP, Ruby, Python and C#. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

These API libraries are maintained by the Positiva Team and we can be reached through our github page.

API Format

All request bodies should have content type application/json and be valid JSON. The Content-Type header must be set in all requests that include a JSON body:

Content-Type: application/json

Endpoint

We currently support both production and sandbox environments using the same endpoint. The token used in the authentication will determine which environment will receive the request.

During development, make sure to use a token created for the sandbox environment.

Endpoint: https://api.gpo.positiva.co.ao/

Authentication

You authenticate to the vPOS API by providing your bearer token in the Authorization header of every request:

Authorization: Bearer [BEARER_TOKEN]

To authenticate, provide the bearer token in the request header:

Transaction Lifecycle

Currently our API provides two methods, Callback and Polling, for performing transactions each with it's own lifecycle.

Callback

  1. Merchant sends transaction request. (See Transactions).
  2. Positiva GPO accepts request.
  3. Once the transaction is completed (accepted or rejected), vPOS calls via HTTP(S) POST the URL specified in the initial request, sending the final transaction data as payload. (See Transaction Schema).

Polling

  1. Merchant sends transaction request. (See Transactions).
  2. Positiva GPO accepts request and provides location to poll request status.
  3. Merchant polls request status periodically until status 303 is received with location header pointing to transaction. (See Poll Request Status).
  4. Merchant queries transaction detail. (See Get Transaction]).

Errors

Positiva GPO API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The resource requested is hidden for administrators only.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- You're requesting too much! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Resources

Transactions

New Payment

const Vpos = require('vpos');

let merchant = new Vpos();

async function payment() {
  return merchant.newPaymentTransaction({amount: "123.45", customer: "900111222"});
}

payment();

require 'vpos'

payment = Vpos.new_payment("900111222", "123.45")

var merchant = new Vpos();

var payment = merchant.newPayment("900111222", "123.45");

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 06a95bd8-2d16-11eb-adc1-0242ac120002" \
  -H "Authorization: Bearer hvHCkChzXuOdMonpeHFxiDEVTfSR9QK5BW4nz6e4XYwWoKsZZjp" \
  "https://vpos.ao/api/v1/transactions" \
  -d '{"type": "payment", "pos_id": 123, "mobile": "900111222", "amount": "123.45",
    "callback_url": "https://your_hostname/link/to/confirm"}'

merchant = Vpos();
payment = merchant.new_payment("900111222", "123.45");

var merchant = new Vpos();
var payment = merchant.NewPayment("900111222", "123.45");

use Vpos\Vpos\Vpos;

$merchant = new Vpos();
$payment = $merchant->newPayment(customer: "900111222", amount: "123.45");

The above command returns structure like this:

HTTP/1.1 202 Accepted
location: /api/v1/requests/1kTFGhJH8i58uD9MdJpMjWnoE

{
  :status_code=>202,
  :message=>"Accepted",
  :location=>"/api/v1/requests/1ksyJpxEmN0lE7Xhpts6drxVq0b"
}

{
  "status_code": 202,
  "message": "Accepted",
  "location": "/api/v1/requests/1mq77owfo4zEyoxbaJHcn4uM2GF"
}

{
  status: 202,
  message: 'Accepted',
  location: '/api/v1/requests/1ksyJpxEmN0lE7Xhpts6drxVq0b'
}

{
  "status_code": 202,
  "message": "Accepted",
  "location": "/api/v1/requests/1mq77owfo4zEyoxbaJHcn4uM2GF"
}

{
  "status_code": 202,
  "message": "Accepted",
  "location": "/api/v1/requests/1mq77owfo4zEyoxbaJHcn4uM2GF"
}

[
  "status_code"=> 202,
  "message"=> "Accepted",
  "location"=> "/api/v1/requests/1mq77owfo4zEyoxbaJHcn4uM2GF"
]

This endpoint creates a new payment transaction.

HTTP Request

POST https://vpos.ao/api/v1/transactions

Payload

Name Type Required Description
type string true Must be set to "payment"
pos_id integer true The POS_ID provided by EMIS
mobile string true The client mobile number in a string format. Must be a number registered in Multicaixa Express.
amount string true Amount of the requested payment in a string format. Use (.) as decimals separator; at most 2 decimal places
callback_url string false Optional parameter to set the callback URL that will receive the transaction details once it completes

Responses

Status Meaning Description
202 Accepted Payment request has been accepted by the gateway for processing and the location to monitor the status is returned in the Location header.
4xx or 5xx Error Please check the error table.

New Refund

const Vpos = require('vpos');

let merchant = new Vpos();

async function refund() {
  return merchant.newRefundTransaction({parentTransactionId: "1ksyJpxEmN0lE7Xhpts6drxVq0b"});
}

refund();

var merchant = new Vpos();

var refund = merchant.newRefund("1ksyJpxEmN0lE7Xhpts6drxVq0b");

require 'vpos'

refund = Vpos.new_refund(1kTFGhJH8i58uD9MdJpMjWnoE)

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 07a95bd8-3d16-21eb-edc1-8242ac120003" \
  -H "Authorization: Bearer hvHCkChzXuOdMonpeHFxiDEVTfSR9QK5BW4nz6e4XYwWoKsZZjp" \
  "https://vpos.ao/api/v1/transactions" \
  -d '{"type": "refund", "parent_transaction_id": "1kTFGhJH8i58uD9MdJpMjWnoE",
     "callback_url": "https://your_hostname/link/to/confirm"}'

merchant = Vpos();
refund = merchant.new_refund("1ksyJpxEmN0lE7Xhpts6drxVq0b");

var merchant = new Vpos();
var refund = merchant.NewRefund("1ksyJpxEmN0lE7Xhpts6drxVq0b");

use Vpos\Vpos\Vpos;

$merchant = new Vpos();
refund = $merchant->newRefund(id: "9kOmKYUWxN0Jpe4PBoXzE");

The above command returns a structure like this:

HTTP/1.1 202 Accepted
location: /api/v1/requests/9gJW9oDUM1YYtUO0Lg

{
  :status_code=>202,
  :message=>"Accepted",
  :location=>"/api/v1/requests/1kt0yqjbe10sYIbKJexPWasZt4D"
}

{
  "status_code": 202,
  "message": "Accepted",
  "location": "/api/v1/requests/1kt0yqjbe10sYIbKJexPWasZt4D"
}

{
  status_code: 202,
  message: 'Accepted',
  location: '/api/v1/requests/1kt0yqjbe10sYIbKJexPWasZt4D'
}

{
  "status_code": 202,
  "message": "Accepted",
  "location": "/api/v1/requests/1kt0yqjbe10sYIbKJexPWasZt4D"
}

{
  "status_code": 202,
  "message": "Accepted",
  "location": "/api/v1/requests/1kt0yqjbe10sYIbKJexPWasZt4D"
}

[
  "status_code"=> 202,
  "message"=> "Accepted",
  "location"=> "/api/v1/requests/1kt0yqjbe10sYIbKJexPWasZt4D"
]

This endpoint creates a new refund transaction. Only full refunds are currently supported.

HTTP Request

POST https://vpos.ao/api/v1/transactions

Payload

Name Type Required Description
type string true The value for this case is a string "refund" representing the type of the transaction.
parent_transaction_id string true This is a string value of the transaction id you're requesting to be refunded.
callback_url string false This is an optional value that expects the callback url that we will call as soon the request has been completed.

Responses

Status Meaning Description
202 Accepted Refund request has been accepted and the location to monitor the status was provided through header location.
4xx or 5xx Error Please check the error table.

New Authorization

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 06a95bd8-2d16-11eb-adc1-0242ac120002" \
  -H "Authorization: Bearer hvHCkChzXuOdMonpeHFxiDEVTfSR9QK5BW4nz6e4XYwWoKsZZjp" \
  "https://vpos.ao/api/v1/transactions" \
  -d '{"type": "authorization", "pos_id": 123, "mobile": "900111222", "amount": "123.45",
    "callback_url": "https://your_hostname/link/to/confirm"}'

The command is submitted for processing and returns a location to check the request status:

HTTP/1.1 202 Accepted
location: /api/v1/requests/1kTFGhJH8i58uD9MdJpMjWnoE

This endpoint creates a new payment authorization transaction. If accepted, funds will be held until an explicit payment with authorization transaction is submitted and accepted or until the authorization is either canceled or expires.

HTTP Request

POST https://vpos.ao/api/v1/transactions

Payload

Name Type Required Description
type string true Must be set to "authorization"
pos_id integer true The POS_ID provided by EMIS
mobile string true The client mobile number in a string format. Must be a number registered in Multicaixa Express.
amount string true Amount to pre-authorize in a string format. Use (.) as decimals separator; at most 2 decimal places
callback_url string false Optional parameter to set the callback URL that will receive the transaction details once it completes

Responses

Status Meaning Description
202 Accepted Payment authorization request has been accepted by the gateway for processing and the location to monitor the status is returned in the Location header.
4xx or 5xx Error Please check the error table.

New Cancelation

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 07a95bd8-3d16-21eb-edc1-8242ac120003" \
  -H "Authorization: Bearer hvHCkChzXuOdMonpeHFxiDEVTfSR9QK5BW4nz6e4XYwWoKsZZjp" \
  "https://vpos.ao/api/v1/transactions" \
  -d '{"type": "cancelation", "parent_transaction_id": "1kTFGhJH8i58uD9MdJpMjWnoE",
    "callback_url": "https://your_hostname/link/to/confirm"}'

The command is submitted for processing and a location to poll the request status is returned:

HTTP/1.1 202 Accepted
location: /api/v1/requests/9gJW9oDUM1YYtUO0Lg

This endpoint creates a new cancelation transaction for a previously accepted authorization.

HTTP Request

POST https://vpos.ao/api/v1/transactions

Payload

Name Type Required Description
type string true Must be set to "cancelation".
parent_transaction_id string true ID of a previously accepted authorization to cancel
callback_url string false This is an optional value that expects the callback url that we will call as soon the request has been completed.

Responses

Status Meaning Description
202 Accepted Refund request has been accepted and the location to monitor the status was provided through header location.
4xx or 5xx Error Please check the error table.

New Payment w/ Authorization

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 06a95bd8-2d16-11eb-adc1-0242ac120002" \
  -H "Authorization: Bearer hvHCkChzXuOdMonpeHFxiDEVTfSR9QK5BW4nz6e4XYwWoKsZZjp" \
  "https://vpos.ao/api/v1/transactions" \
  -d '{"type": "payment", "parent_transaction_id": "1kTFGhJH8i58uD9MdJpMjWnoE", "amount": "123.45",
    "callback_url": "https://your_hostname/link/to/confirm"}'

The command is submitted for processing a a location to check the status is returned:

HTTP/1.1 202 Accepted
location: /api/v1/requests/1kTFGhJH8i58uD9MdJpMjWnoE

This endpoint creates a new payment transaction from a previously accepted authorization, efectively capturing the amount.

HTTP Request

POST https://vpos.ao/api/v1/transactions

Payload

Name Type Required Description
type string true Must be set to "payment"
parent_transaction_id string true The ID of the accepted authorization transaction
amount string true Amount to capture. Must be equal or less than the amount of the authorization. Use (.) as decimals separator; at most 2 decimal places
callback_url string false Optional parameter to set the callback URL that will receive the transaction details once it completes

Responses

Status Meaning Description
202 Accepted Payment request has been accepted by the gateway for processing and the location to monitor the status is returned in the Location header.
4xx or 5xx Error Please check the error table.

Get Transaction

const Vpos = require('vpos');

let merchant = new Vpos();

async function transaction() {
  return merchant.getTransaction({transactionId: "1jHbXEbRTIbbwaoJ6w06nLcRG7X"});
}

transaction();

require 'vpos'
transactions = Vpos.get_transaction("1jHbXEbRTIbbwaoJ6w06nLcRG7X")

var merchant = new Vpos();
var transaction = merchant.getTransaction("1jHbXEbRTIbbwaoJ4w05nLcRG7C");

curl "https://vpos.ao/api/v1/transactions/1jHbXEbRTIbbwaoJ6w06nLcRG7X" \
  -H "Authorization: Bearer hvHCkChzXuOdMonpeHFxiDEVTfSR9QK5BW4nz6e4XYwWoKsZZjp"

merchant = Vpos();
transaction = merchant.get_transaction("1jHbXEbRTIbbwaoJ4w05nLcRG7C");

var merchant = new Vpos();
var transaction = merchant.GetTransaction("1jHbXEbRTIbbwaoJ4w05nLcRG7C");

use Vpos\Vpos\Vpos;

$merchant = new Vpos();
$transaction = $merchant->getTransaction("9kOmKYUWxN0Jpe4PBoXzE");

The above command returns a structure like this:

{
  "amount": "101.09",
  "clearing_period": null,
  "id": "1jHbXEbRTIbbwaoJ6w06nLcRG7X",
  "mobile": "900111222",
  "parent_transaction_id": null,
  "pos_id": 100,
  "status": "accepted",
  "status_datetime": "2020-10-23T14:41:00Z",
  "status_reason": null,
  "type": "payment"
}

{
  :status_code=>200,
  :message=>"OK",
  :data=>
  {
    "amount"=>"101.09",
    "clearing_period"=>nil,
    "id"=>"1jHbXEbRTIbbwaoJ6w06nLcRG7X",
    "mobile"=>"931554707",
    "parent_transaction_id"=>nil,
    "pos_id"=>445,
    "status"=>"accepted",
    "status_datetime"=>"2020-10-23T14:41:00Z",
    "status_reason"=>nil,
    "type"=>"payment"
  }
}

{
  "status_code": 200,
  "message": "OK",
  "data": {
    "amount": "101.09",
    "clearing_period": null,
    "id": "1jHbXEbRTIbbwaoJ6w06nLcRG7X",
    "mobile": "900111222",
    "parent_transaction_id": null,
    "pos_id": 100,
    "status": "accepted",
    "status_datetime": "2020-10-23T14:41:00Z",
    "status_reason": null,
    "type": "payment"
  }
}

{
  status_code: 200,
  message: 'OK',
  data: [
    {
      amount: '101.09',
      clearing_period: null,
      id: '1jHbXEbRTIbbwaoJ6w06nLcRG7X',
      mobile: '900111222',
      parent_transaction_id: null,
      pos_id: 100,
      status: 'accepted',
      status_datetime: '2020-10-23T14:41:00Z',
      status_reason: null,
      type: 'payment'
    }
  ]
}

{
  "status_code": 200,
  "message": "OK",
  "data": {
    "amount": "101.09",
    "clearing_period": null,
    "id": "1jHbXEbRTIbbwaoJ6w06nLcRG7X",
    "mobile": "900111222",
    "parent_transaction_id": null,
    "pos_id": "100",
    "status": "accepted",
    "status_datetime": "2020-10-23T14:41:00Z",
    "status_reason": null,
    "type": "payment"
  }
}

{
  "status": 200,
  "message": "OK",
  "data": {
    "amount": "101.09",
    "clearing_period": null,
    "id": "1jHbXEbRTIbbwaoJ6w06nLcRG7X",
    "mobile": "900111222",
    "parent_transaction_id": null,
    "pos_id": 100,
    "status": "accepted",
    "status_datetime": "2020-10-23T14:41:00Z",
    "status_reason": null,
    "type": "payment"
  }
}

[
  "status_code"=> 200,
  "message"=> "OK",
  "data"=> "
  {
    "amount":"101.09",
    "clearing_period":null,
    "id":"1jHbXEbRTIbbwaoJ6w06nLcRG7X",
    "mobile":"931554707",
    "parent_transaction_id":null,
    "pos_id":445,
    "status":"accepted",
    "status_datetime":"2020-10-23T14:41:00Z",
    "status_reason":null,
    "type":"payment"
  }"
]

This endpoint retrieves a specific transaction.

HTTP Request

GET https://vpos.ao/api/v1/transactions/<ID>

URL Parameters

Parameter Description
ID The ID of the transaction to retrieve

Responses

Status Meaning Description
200 OK Transaction has been retrieved.
4xx or 5xx Error Please check the error table. 
const Vpos = require('vpos');

let merchant = new Vpos();

async function payment() {
  return merchant.newPaymentTransaction({amount: "123.45", customer: "900111222"});
}

payment();

require 'vpos'

payment = Vpos.new_payment("900111222", "123.45")

var merchant = new Vpos();

var payment = merchant.newPayment("900111222", "123.45");

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 06a95bd8-2d16-11eb-adc1-0242ac120002" \
  -H "Authorization: Bearer hvHCkChzXuOdMonpeHFxiDEVTfSR9QK5BW4nz6e4XYwWoKsZZjp" \
  "https://vpos.ao/api/v1/transactions" \
  -d '{"type": "payment", "pos_id": 123, "mobile": "900111222", "amount": "123.45",
    "callback_url": "https://your_hostname/link/to/confirm"}'

merchant = Vpos();
payment = merchant.new_payment("900111222", "123.45");

var merchant = new Vpos();
var payment = merchant.NewPayment("900111222", "123.45");

use Vpos\Vpos\Vpos;

$merchant = new Vpos();
$payment = $merchant->newPayment(customer: "900111222", amount: "123.45");

The above command returns structure like this:

HTTP/1.1 202 Accepted
location: /api/v1/requests/1kTFGhJH8i58uD9MdJpMjWnoE

{
  :status_code=>202,
  :message=>"Accepted",
  :location=>"/api/v1/requests/1ksyJpxEmN0lE7Xhpts6drxVq0b"
}

{
  "status_code": 202,
  "message": "Accepted",
  "location": "/api/v1/requests/1mq77owfo4zEyoxbaJHcn4uM2GF"
}

{
  status: 202,
  message: 'Accepted',
  location: '/api/v1/requests/1ksyJpxEmN0lE7Xhpts6drxVq0b'
}

{
  "status_code": 202,
  "message": "Accepted",
  "location": "/api/v1/requests/1mq77owfo4zEyoxbaJHcn4uM2GF"
}

{
  "status_code": 202,
  "message": "Accepted",
  "location": "/api/v1/requests/1mq77owfo4zEyoxbaJHcn4uM2GF"
}

[
  "status_code"=> 202,
  "message"=> "Accepted",
  "location"=> "/api/v1/requests/1mq77owfo4zEyoxbaJHcn4uM2GF"
]

Transaction Schema, Status and Status Reason

Schema

The following table details the transaction schema used in vPOS:

Attibute Type Nullable Max. Length Comments
Id string false 30
type string false 10 Values: "payment" or "refund"
pos_id integer true Can be null in a refund with invalid parent_transaction_id
parent_transaction_id string true 30 Set if refund, null if payment
clearing_period integer true POS clearing period
mobile string true 9 Can be null in a refund with invalid parent_transaction_id
amount string true 20 Can be null in a refund with invalid parent_transaction_id; Dot(.) as decimals separator;at most 2 decimal places
status string false "accepted" or "rejected" (See Status)
status_datetime string false ISO8601 datetime
status_reason string true 20 Set if status is "rejected" (See Status Reason)

Status

Status Reason

Gateway

Code Meaning
1000 Generic gateway error
1001 Request timed-out and will not be processed
1002 Gateway is not authorized to execute transactions on the specified POS
1003 Parent transaction is not valid for the request

Processor

Code Meaning
2000 Generic processor error
2001 Insufficient funds in client's account
2002 Refused by the card issuer
2003 Card or network daily limit exceeded
2004 Request timed-out and was refused by the processor
2005 POS is closed and unable to accept transactions
2006 Insufficient funds in POS available for refund
2007 Invalid or Inactive supervisor card
2008 Invalid merchant email
2009 Parent transaction is too old to be refunded
2010 Request was refused by the processor
2011 Payment amount exceeds Authorization amount
2012 Parent transaction already processed

Client

Code Meaning
3000 Refused by client

Idempotency

To ensure the client application can implement a simple retry mechanism to handle timeouts, due to temporary communication failures with the API, an optional custom HTTP header "Idempotency-Key" can be included in the request of a new payment or refund transaction.

The Idempotency-Key should include a random and unique string. When retrying, the same value MUST be passed.

The server will cache the value along with the input parameters in the request payload. The following logic will be applied:

The cache entries will be stored for 60 minutes, ensuring the server will keep a de-duplication window of 1 hour.

Requests

Get Request


const Vpos = require('vpos');

let merchant = new Vpos();

async function requestStatus() {
  return merchant.getRequest({requestId: "1kt0yqjbe10sYIbKJexPWasZt4D"});
}

requestStatus();

var merchant = new Vpos();

var payment = merchant.newPayment("900111222", "123.45");
var transactionId = merchant.getTransactionId(payment);

var request = merchant.getRequest(transactionId);

require 'vpos'
transactions = Vpos.get_request("1jHbXEbRTIbbwaoJ6w06nLcRG7X")

curl "https://vpos.ao/api/v1/requests/1jHbXEbRTIbbwaoJ6w06nLcRG7X" \\
  -H "Authorization: Bearer hvHCkChzXuOdMonpeHFxiDEVTfSR9QK5BW4nz6e4XYwWoKsZZjp"

merchant = new Vpos();

payment = merchant.new_payment("900111222", "123.45");
transactionId = merchant.get_request_id(payment);

request = merchant.get_request(transactionId);

var merchant = new Vpos();

var payment = merchant.NewPayment("900111222", "123.45");
string requestID = payment.GetRequestID();
Request request = merchant.GetRequest(requestID);

$merchant = new Vpos();
$payment = $merchant->newPayment(customer: "931554707", amount: "123.45");

$request_id = $merchant->getRequestId($payment);
$request = $merchant->getRequest(id: $request_id);

The above command returns a structure like this:

Response (While request is queued or running)

{
  "inserted_at": "2020-10-22T09:45:45Z",
  "eta": "120"
}

{
  :status_code=>200,
  :message=>"OK",
  :data=>
  {
    "eta"=>119.0,
    "inserted_at"=>"2020-11-29T13:08:26Z"
  }
}

{
  "status_code": 200,
  "message": "OK",
  "data": {
    "eta": 119.0,
    "inserted_at": "2020-11-29T13:08:26Z"
  }
}

{
  inserted_at: '2020-10-22T09:45:45Z',
  eta: '120'
}

{
  "status_code": 200,
  "message": "OK",
  "data": {
    "eta": 119.0,
    "inserted_at": "2020-11-29T13:08:26Z"
  }
}

{
  "status_code": 200,
  "message": "OK",
  "data": {
    "eta": 119.0,
    "inserted_at": "2020-11-29T13:08:26Z"
  }
}

[
  "status_code"=> 200,
  "message"=> "OK",
  "data"=> "{
    "eta": 119.0,
    "inserted_at": "2020-11-29T13:08:26Z"
  }"
]

Response (Once request completes)

HTTP/1.1 303 See Other
location: /api/v1/transactions/9gJW9oDUM1YYtUO0Lg

{
  :status_code=>303,
  :message=>"See Other",
  :location=>"/api/v1/transactions/1kyAYrh2lN8dwrILa44RV2GrXcz"
}

{
  "status_code": 303,
  "message": "See Other",
  "data": "/api/v1/transactions/1kyAYrh2lN8dwrILa44RV2GrXcz"
}

{
  status_code: 303,
  message: 'See Other,
  location: '/api/v1/transactions/1kyAYrh2lN8dwrILa44RV2GrXcz'
}

{
  "status_code": 303,
  "message": "See Other",
  "data": "/api/v1/transactions/1kyAYrh2lN8dwrILa44RV2GrXcz"
}

{
  "status_code": 303,
  "message": "See Other",
  "data": "/api/v1/transactions/1kyAYrh2lN8dwrILa44RV2GrXcz"
}

[
  "status_code"=> 303,
  "message"=> "See Other",
  "data"=> "/api/v1/transactions/1kyAYrh2lN8dwrILa44RV2GrXcz"
]

This endpoint retrieves a specific requested transaction.

HTTP Request

GET https://vpos.ao/api/v1/requests/<ID>

URL Parameters

Parameter Description
ID The ID returned at the Location header at the POST transaction

Response

HTTP Status

Status Meaning Description
200 Accepted Payment or Refund request has been accepted and the location to monitor the status was provided through header location.
303 See Other Payment or Refund request has finished processing and was relocated to the location provided through header location.
4xx or 5xx Error Please check the error table.

Sandbox

When using the sandbox environment please check information below.

Testing

Mobile

The mobile number you pass for the requests will determine the final status of the transaction.

Mobile Status Reason Details
900000000 accepted N/A Simulates an accepted transaction by the client. Occurs 5 to 20 seconds after request.
900002004 rejected 2004 Simulates the timeout incurred when the client receives the payment request but fails to accept within the time limit. Occurs 90 seconds after request.
900003000 rejected 3000 Simulates a client refusal. Occurs in 5 to 20 seconds after request.
9XXXXXXXX rejected 2010 Simulates a refusal from the processor. Occurs immediately after request.

Plugins

WooCommerce

This is the official WordPress/WooCommerce plugin for Positiva GPO WooCommerce maintained as OSS at github.

Libraries

Configuration

Our libraries expect you to set up the following environment variables on your machine before interacting with the API:

Variable Description Required
GPO_POS_ID The Point of Sale ID provided by EMIS true
MERCHANT_POSITIVA_GPO_TOKEN The API token provided by vPOS used for authentication true
PAYMENT_CALLBACK_URL The callback URL you specify that will handle payment notifications false
REFUND_CALLBACK_URL The callback URL you specify that will handle refund notifications false
POSITIVA_GPO_ENVIRONMENT The Positiva GPO environment, leave empty for sandbox mode and use "PRD" for production. true

Don't have this information? Talk to us

Given you have set up all the environment variables above with the correct information, you will now be able to authenticate and communicate with our API.

Languages

Java

This is the official library for Positiva GPO Java maintained as OSS at github.

Javascript

This is the official library for Positiva GPOJavascript maintained as OSS at github.

PHP

This is the official library for Positiva GPO PHP maintained as OSS at github.

Python

This is the official library for Positiva GPO Python maintained as OSS at github.

Ruby

This is the official library for Positiva GPO Ruby maintained as OSS at github.

C#

This is the official library for Positiva GPO C# maintained as OSS at github.

cURL Java Javascript PHP Ruby Python C#