Bank Transfer Payment
Initialize a bankTransfer transaction.
OPay Bank Transfer Payment
For calling the API using the POST method you can use these endpoints URL:
In case you are still in the developing phase, use the following staging API endpoint URL
https://testapi.opaycheckout.com/api/v1/international/payment/create
Once you are ready for production, you should use the following production API endpoint URL instead
https://liveapi.opaycheckout.com/api/v1/international/payment/create
Request Parameters:
- Header: Authorization(API Calls Signature), MerchantId
- Json object containing the transaction information:
Authorization : Bearer {signature}
MerchantId : 256612345678901
{
"amount":{
"currency":"NGN",
"total":400
},
"callbackUrl":"https://testapi.opaycheckout.com/api/v1/international/print",
"country":"NG",
"customerName":"customerName",
"payMethod":"BankTransfer",
"product":{
"description":"dd",
"name":"name"
},
"reference":"12345a",
"userInfo":{
"userEmail":"test@email.com",
"userId":"userid001",
"userMobile":"+23488889999",
"userName":"David"
},
"userPhone":"+1234567879"
}
HTTP POST parameters
Here is a detailed description for the parameters you need to complete the POST request:
An example call of Bank Transfer Payment API is as follows :
class BankTransferController
{
private $secretkey;
private $merchantId;
private $url;
public function __construct() {
$this->merchantId = '256622011275597';
$this->secretkey = 'OPAYPRV1641***********926';
$this->url = 'https://testapi.opaycheckout.com/api/v1/international/payment/create';
}
public function test(){
$data = [
'amount'=>
[
'currency'=>'NGN',
'total'=>400
],
'callbackUrl'=>'https://testapi.opaycheckout.com/api/v1/international/print',
'country'=>'NG',
'customerName'=>'customerName',
'payMethod'=>'BankTransfer',
'product'=>
[
'description'=>'dd',
'name'=>'name'
],
'reference'=>"12345a",
'userInfo' => [
"userEmail"=> 'xxx@xxx.com',
"userId"=> 'userid001',
"userMobile"=> '13056288895',
"userName"=> 'xxx',
],
'userPhone'=>'+1234567879'
];
$data2 = (string) json_encode($data,JSON_UNESCAPED_SLASHES);
$auth = $this->auth($data2);
$header = ['Content-Type:application/json', 'Authorization:Bearer '. $auth, 'MerchantId:'.$this->merchantId];
$response = $this->http_post($this->url, $header, json_encode($data));
$result = $response?$response:null;
return $result;
}
private function http_post ($url, $header, $data) {
if (!function_exists('curl_init')) {
throw new Exception('php not found curl', 500);
}
$ch = curl_init();
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$response = curl_exec($ch);
$httpStatusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error=curl_error($ch);
curl_close($ch);
if (200 != $httpStatusCode) {
print_r("invalid httpstatus:{$httpStatusCode} ,response:$response,detail_error:" . $error, $httpStatusCode);
}
return $response;
}
public function auth ( $data ) {
$secretKey = $this->secretkey;
$auth = hash_hmac('sha512', $data, $secretKey);
return $auth;
}
}
const request = require('request');
var sha512 = require('js-sha512');
const formData = {
"amount":{
"currency":"NGN",
"total":400
},
"callbackUrl":"https://testapi.opaycheckout.com/api/v1/international/print",
"country":"NG",
"customerName":"customerName",
"payMethod":"BankTransfer",
"product":{
"description":"dd",
"name":"name"
},
"reference":"123456",
"userInfo":{
"userEmail":"xxx@xxx.com",
"userId":"userid001",
"userMobile":"13056288895",
"userName":"xxx"
},
"userPhone":"+1234567879"
};
var privateKey = "OPAYPRV1641***********926"
var hash = sha512.hmac.create(privateKey);
hash.update(JSON.stringify(formData));
hmacsignature = hash.hex();
console.log(hmacsignature)
request({
url: 'https://testapi.opaycheckout.com/api/v1/international/payment/create',
method: 'POST',
headers: {
'MerchantId': '256622011275597',
'Authorization': 'Bearer '+hmacsignature
},
json: true,
body: formData
}, function (error, response, body) {
console.log('body: ')
console.log(body)
}
)
curl --location --request POST 'https://testapi.opaycheckout.com/api/v1/international/payment/create' \
--header 'MerchantId: 256622011275597' \
--header 'Authorization: Bearer 0fbef225fb948facb873c34f3c3f756bee40e56f879f01269f941e2cfa9653f2afdcb6720151494434a88c7d0bb6bbce6708b7ca4db714bb97a80962129d2cea' \
--header 'Content-Type: application/json' \
--data-raw '{
"country": "NG",
"orderNo": "220207140591969743",
"otp": "000000"
}'
import com.google.gson.Gson;
import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.TreeMap;
import java.util.UUID;
public class BankTransfer {
private static final String privateKey = "OPAYPRV1641***********926";
private static final String endpoint = "https://testapi.opaycheckout.com";
private static final String merchantId = "256622011275597";
public static void main(String[] args) throws Exception {
String addr = endpoint + "/api/v1/international/payment/create";
Gson gson = new Gson();
TreeMap order = new TreeMap<>();
TreeMap amount = new TreeMap<>();
amount.put("currency","NGN");
amount.put("total",400);
order.put("amount",amount);
order.put("callbackUrl","https://testapi.opaycheckout.com/api/v1/international/print");
order.put("country","NG");
order.put("customerName","customerName");
order.put("payMethod","BankTransfer");
TreeMap product = new TreeMap<>();
product.put("description","dd");
product.put("name","name");
order.put("product",product);
TreeMap userInfo = new TreeMap<>();
userInfo.put("userEmail","test@email.com");
userInfo.put("userId","userid001");
userInfo.put("userMobile","+23488889999");
userInfo.put("userName","David");
order.put("userInfo",userInfo);
order.put("reference", UUID.randomUUID().toString());
order.put("userPhone","+1234567879");
String requestBody = gson.toJson(order);
System.out.println("--request:");
System.out.println(requestBody);
String oPaySignature = hmacSHA512(requestBody, privateKey);
System.out.println("--signature:");
System.out.println(oPaySignature);
URL url = new URL(addr);
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json; utf-8");
con.setRequestProperty("Authorization", "Bearer "+oPaySignature);
con.setRequestProperty("MerchantId", merchantId);
con.setDoOutput(true);
OutputStream os = con.getOutputStream();
byte[] input = requestBody.getBytes(StandardCharsets.UTF_8);
os.write(input, 0, input.length);
BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream(), StandardCharsets.UTF_8));
StringBuilder response = new StringBuilder();
String responseLine = null;
while ((responseLine = br.readLine()) != null) {
response.append(responseLine.trim());
}
System.out.println("--response:");
System.out.println(response.toString());
//close your stream and connection
}
public static String hmacSHA512(final String data, final String secureKey) throws Exception{
byte[] bytesKey = secureKey.getBytes();
final SecretKeySpec secretKey = new SecretKeySpec(bytesKey, "HmacSHA512");
Mac mac = Mac.getInstance("HmacSHA512");
mac.init(secretKey);
final byte[] macData = mac.doFinal(data.getBytes());
byte[] hex = new Hex().encode(macData);
return new String(hex, StandardCharsets.UTF_8);
}
}
Header must contain the "Signature" , "MerchantId"
Signature is calculated using SHA-512 HMAC signed with your Private Key. See API Calls Signature section for more details.
Bank Transfer Payment Response
Response Parameters:
The parameters contained in the response received whenever you call the Transaction Create API as a JSON Object.
{
"code": "00000",
"message": "SUCCESSFUL",
"data": {
"reference": "testbyqur1641800843000",
"orderNo": "220110144664537659",
"nextAction": {
"actionType": "TRANSFER_ACCOUNT",
"transferAccountNumber": "7827845341",
"transferBankName": "WEMA BANK",
"expiredTimestamp": 1641773850
},
"status": "PENDING",
"amount": {
"total": 400,
"currency": "NGN"
},
"vat": {
"total": 0,
"currency": "NGN"
}
}
}
Here is a detailed description for the parameters received in the response:
Parameter | type | Description | example | |
---|---|---|---|---|
reference | String |
Unique merchant payment order number. | 937102167 | |
orderNo | String |
Unique Opay payment order number. | 211004140885521681 | |
status | enum |
[INITIAL, PENDING, SUCCESS, FAIL, CLOSE] | SUCCESS | |
amount | ||||
currency | String |
Currency | NGN | |
total | Long |
amount(cent unit). | 400 | |
vat | ||||
currency | String |
Currency | NGN | |
total | Long |
amount(cent unit). | 10 | |
nextAction | ||||
actionType | String |
Next action type | TRANSFER_ACCOUNT | |
transferAccountNumber | String |
transferAccountNumber | "7822719543" | |
transferBankName | String |
transferBankName | "WEMA BANK" | |
expiredTimestamp | String |
expiredTimestamp | 1644572675 | |
failureCode | String |
fail error code. | payment fail error code, not blank when status [FAIL/CLOSE] | |
failureReason | String |
fail error message. | payment fail error message, not blank when status [FAIL/CLOSE] |
Error Handling
After submitting an API call to OPay, you receive a response back to inform you that
your request was received and processed. A successful OPay API should return a status code 00
,
meanwhile, in a situation where any payment processing error occurred, you will receive an error code with a
message to describe the reason of the error. A sample error response can be found below.
{
"code": "02006",
"message": "payment not found."
}
Depending on the HTTP status code of the response, you should build some logic to handle any errors that a request or the system may return. A list of possible potential error codes that you may receive can be found below.
Error Code | Error Message |
---|---|
02000 | authentication failed. |
02001 | request params not valid. |
02003 | payMethod not support. |
02004 | the payment reference already exists. |
02002 | merchant not configured with this function. |
02007 | merchant not available. |
50003 | service not available, please try again. |