Confirm Transaction

POST {api-url}/confirm?ns={community}

Use this call to finalize a transaction previously held in a pending state. This provides a robust handling for complex payment scenarios (e.g., partial payments) by allowing the merchant to either complete the transaction (confirm) or cancel it (reverse).

Critical Step

This call is a critical step in the payment lifecycle. To prevent failed or abandoned payments and ensure a robust handling of all transaction outcomes, you are required to use the /confirm call to finalize every transaction. Failure to do so will result in transactions being automatically reversed at the end of the day.

Request

Parameters

Field	Type	Requirement	Description
Amount	String	Required	Whether to confirm or reverse this transaction (-1 to confirm, 0 to reverse).
OldReference	String	Required**	The reference number given to the original transaction.
TID	String	Required**	TID (Transaction ID) of the executed payment response.
Reference	String	Optional*	A new unique transaction reference number given by the merchant.
Metadata	String	Optional	Any other detail that the merchant wishes to store on this transaction.

*Reference numbers must be unique identifiers otherwise an error will be returned.

**Either the TID or OldReference must be supplied. If both are supplied, OldReference will be used.

Example Body

{
  "Amount": "-1",
  "OldReference": "101",
  "TID": "14975698673",
  "Reference": "111",
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}

Response

Parameters

Field	Type	Description
TID	String	TID (Transaction ID) of the executed payment response.
Reference	String	The new transaction reference number.
OldReference	String	The reference number of the original transaction.
Created	String	Transaction execution time (YYYY/MM/DD HH:MM).
State	String	Transaction state (Confirmed or Refunded).
Status	String	Transaction status code (1 or negative error code).
Error	String	Failure reason, if applicable.

Example Body

{
  "TID": "14975698685",
  "Reference": "111",
  "OldReference": "101",
  "Created": "2024/05/11 12:00",
  "State": "Confirmed",
  "Status": "1",
  "Error": ""
}

cURL

curl -X POST '{api-url}/confirm?ns={community}' \
-H 'Authorization: bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"Amount":"-1","OldReference":"101","TID":"14975698673","Reference":"111","Metadata":"{\"ActorUserIDs\": \"547828938941114\"}"}'

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        var request = new HttpRequestMessage(HttpMethod.Post, "{api-url}/confirm?ns={community}");
        request.Headers.Add("Authorization", "bearer YOUR_TOKEN");

        var jsonPayload = @"{
  ""Amount"": ""-1"",
  ""OldReference"": ""101"",
  ""TID"": ""14975698673"",
  ""Reference"": ""111"",
  ""Metadata"": ""{\""ActorUserIDs\"": \""547828938941114\""}""
}";
        request.Content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

        var response = await client.SendAsync(request);
        response.EnsureSuccessStatusCode();

        var responseBody = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseBody);
    }
}

Go

package main

import (
  "fmt"
  "io/ioutil"
  "net/http"
  "strings"
)

func main() {
  url := "{api-url}/confirm?ns={community}"
  payload := strings.NewReader(`{"Amount":"-1","OldReference":"101","TID":"14975698673","Reference":"111","Metadata":"{\"ActorUserIDs\": \"547828938941114\"}"}`)

  req, _ := http.NewRequest("POST", url, payload)
  req.Header.Add("Authorization", "bearer YOUR_TOKEN")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()

  body, _ := ioutil.ReadAll(res.Body)
  fmt.Println(string(body))
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ApiRequest {
    public static void main(String[] args) throws Exception {
        var payload = """
                {
  "Amount": "-1",
  "OldReference": "101",
  "TID": "14975698673",
  "Reference": "111",
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}
                """;

        var request = HttpRequest.newBuilder()
                .uri(URI.create("{api-url}/confirm?ns={community}"))
                .header("Authorization", "bearer YOUR_TOKEN")
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(payload))
                .build();

        var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Node.js

// Requires Node.js v18+
(async () => {
    const url = '{api-url}/confirm?ns={community}';
    const payload = {
    "Amount": "-1",
    "OldReference": "101",
    "TID": "14975698673",
    "Reference": "111",
    "Metadata": {
        "ActorUserIDs": "547828938941114"
    }
};

    try {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Authorization': 'bearer YOUR_TOKEN',
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(payload)
        });
        const data = await response.json();
        console.log(data);
    } catch (error) {
        console.error('Error:', error);
    }
})();

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{api-url}/confirm?ns={community}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
  "Amount": "-1",
  "OldReference": "101",
  "TID": "14975698673",
  "Reference": "111",
  "Metadata": "{\"ActorUserIDs\": \"547828938941114\"}"
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: bearer YOUR_TOKEN',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);
curl_close($curl);
echo $response;

Python

import requests
import json

url = "{api-url}/confirm?ns={community}"
payload = {
  "Amount": "-1",
  "OldReference": "101",
  "TID": "14975698673",
  "Reference": "111",
  "Metadata": {
    "ActorUserIDs": "547828938941114"
  }
}

headers = {
    "Authorization": "bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Ruby

require 'uri'
require 'net/http'
require 'json'

url = URI("{api-url}/confirm?ns={community}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'bearer YOUR_TOKEN'
request["Content-Type"] = 'application/json'

request.body = JSON.dump({
  "Amount": "-1",
  "OldReference": "101",
  "TID": "14975698673",
  "Reference": "111",
  "Metadata": {
    "ActorUserIDs": "547828938941114"
  }
})

response = http.request(request)
puts response.read_body