Server to Server
The Transactions API allows you create and manage payments on your integration.
This Server 2 Server Version 1 is for NGN transaction only. To use other currencies, kindly use Version 2
- Encrypt your Card (Card Number, Expiry Date, CVV and PIN) with
- Pass your secret key as the Bearer token in Authorization Header.
Card Encryption
Card Encryption: perform aes-128-cbc encryption on your card payload using your secret_key and reference
To generate a test card encryption, kindly use our test encryption endpoint below
NOTE:The purpose of this endpoint is to test if your encryption from your codebase is correct or not. It is not safe to send live card details without encrypting your card. You are adviced to perform live encryption in your codebase in order to secure your card details.
Endpoint: /test/encryption
Method: POST
Header
| Param | Type | Required? | Decription |
|---|---|---|---|
| authorization | string | Yes | Set value to Bearer SECRET_KEY |
| content-type | string | Yes | Set value to application/json |
Card Encryption Payload
{
"data" :{
"number": "5123450000000008",
"expiryMonth": "10",
"expiryYear": "22",
"cvv" : "100",
"pin" : "1234" // (optional - only required for verve/local cards)
},
"reference": "1253627873656276350"
}
Card Encryption Output
{
"card" :"83fa6763bb31bae36a74f787ab814514aeede91fcdb311fd67609b414c5e5ea2751a47870c8717e71bcbc9c33287a3d6af9ffae8e2edbf2de1e2694384d699b020d31492637eef60d7a63f303798363a"
}
Initialize Transaction (S2S)
Initialize a transaction from your backend.
You are required to parse your card encryption output as card parameter in your Transaction Initialize payload.
Endpoint: /transaction/initialize
Method: POST
Header
| Param | Type | Required? | Decription |
|---|---|---|---|
| authorization | string | Yes | Set value to Bearer SECRET_KEY |
| content-type | string | Yes | Set value to application/json |
Sample Post
curl https://api.budpay.com/api/s2s/transaction/initialize
-H "Authorization: Bearer YOUR_SECRET_KEY"
-H "Content-Type: application/json"
-d '{ "amount": "100", "card" :"83fa6763bb31bae36a74f787ab814514aeede91fcdb311fd67609b414c5e5ea2751a47870c8717e71bcbc9c33287a3d6af9ffae8e2edbf2de1e2694384d699b020d31492637eef60d7a63f303798363a", "currency": "USD", "email": "test@email.com", "reference": "1253627873656276350" }'
-X POST
Sample Post (Json version)
{
"amount": "2",
"card": "83fa6763bb31bae36a74f787ab814514aeede91fcdb311fd67609b414c5e5ea2751a47870c8717e71bcbc9c33287a3d6af9ffae8e2edbf2de1e2694384d699b020d31492637eef60d7a63f303798363a",
"callback":"www.budpay.com",
"currency": "NGN",
"email": "test@email.com",
"pin" : "1234",
"reference": "123253627873blsample29NEvccZzzl"
}
Request Body Params
This explains what parameters are required and which are optional base on the Card Type
| Param | Type | Mastercard | Visa | Verve | Decription |
|---|---|---|---|---|---|
| amount | string | Required | Required | Required | payment value |
| card | string | Required | Required | Required | the output from your card encryption |
| callback | string | Required | Required | Required | your callback url |
| currency | string | Required | Required | Required | your transaction currency i.e NGN |
| string | Required | Required | Required | customer email | |
| pin | string | Not Required | Required | Required | card pin |
| reference | string | Required | Required | Required | a unique identifier |
For Mastercard and Visa card transaction, you will get the next step response (3DS2), while Verve card transaction will take you to the final response (Payment Successful).
3DS2 Sample Response
{
"status": true,
"message": "Proceed authentication 3DS2",
"data": "<div id=\"initiate3dsSimpleRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\" > </iframe> <form id =\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"https://secure-acs2ui-b1.wibmo.com/v1/acs/services/threeDSMethod/8528?cardType=M\" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9ldS5nYXRld2F5Lm1hc3RlcmNhcmQuY29tL2NhbGxiYWNrSW50ZXJmYWNlL2dhdGV3YXkvOGFkZGRiNzE1MTQwMjk2OWMxMmI1Y2QzNjBhOTdmYTdiZTE1ZWU1NWZiZDEwZTE5MmI3ZDIwNDcxNmQxYTVlNSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiZjgxNGM3YWMtMmRiOS00Nzg1LThhMjYtYjA2NjZlYTBjMGVkIn0=\" /> </form> <script id=\"initiate-authentication-script\"> var e=document.getElementById(\"initiate3dsSimpleRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>",
"_links": {
"url": "http://api.budpay.com/api/mastercard-payment/3ds2auth",
"method": "POST",
"payload": [
"ref"
]
}
}
You are required to open the 3DS2 Response data html in a hidden page to run in background for 20 seconds and then hit the _links endpoint in the response to proceed. After that you will get the Final Response.
Note: You will receive 3DS2 response for cards that support 3DS2. If not, you will get the Final Response instead.
Final Sample Response (Matercard & Visa)
{
"status": "success",
"message": "Approved or Captured"
}
NOTE: Before giving value to your customers, kindly confirm if the “STATUS is SUCCESSFUL, and the MESSAGE is either APPROVED or CAPTURED.”
Parameters
| Param | Type | Required? | Decription |
|---|---|---|---|
| string | Yes | Customer email address | |
| amount | string | Yes | Amount you are debiting customer. Do not pass this if creating subscriptions. |
| card | string | Yes | Encrypted Card output from card encryption. |
| currency | string | no | Currency charge should be performed in. Allowed values are: NGN, USD or GBP It defaults to your integration currency. Default currency set to NGN when currency parameter is not set |
| reference | string | Yes | Unique case sensitive transaction reference. Only -,_,., =and alphanumeric characters allowed. |
3DS2 Flow Diagram
Final Sample Response (Verve Card)
{
"status": true,
"message": "Payment Successful"
}