# Introduction Integrate our APIs into your application Seerbit is a secured gateway for every payment need in the market space. The Seerbit API helps you create your own payments flow from e-commerce to recurring payments, payouts and everything in between. # Authentication Each API request that you make to SeerBit must be authenticated using the bearer token authentication type. ## Authentication `POST` `https://seerbitapi.com/api/v2/encrypt/keys` #### Request Body | Name | Type | Description | | ------------------------------------- | ------ | ------------------------------------------------------------ | | key\* | string | consists of your privatekey and publickey seperated by a '.' | {% tabs %} {% tab title="200: OK Success" %} ```json { "status": "SUCCESS", "data": { "code": "00", "EncryptedSecKey": { "encryptedKey": "SNt8kjeVjsdTG4lPlwg6sTvpVAay2RA7hoCEzHPkIQa+MNfDepx4VBr5JMgLb5Q5anq9XoN2pXU850bumqBWFVw1T1ZW5w8N+Sq/" }, "message": "Successful" } } ``` {% endtab %} {% tab title="400: Bad Request Bad Request" %} 
{
  "message": "Bad Request",
  "error": "There has been a problem with reading or understanding the request."
}
{% endtab %} {% tab title="404: Not Found Not Found" %} 
{
  "error": "Not Found"
}
{% endtab %} {% tab title="500: Internal Server Error Internal Server Error" %} ```json { "message": "Internal Server Error", "error": "PROCESSING" } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="CURL" %} ```json curl --location --request OPTIONS 'https://seerbitapi.com/api/v2/encrypt/keys' \ --header 'Content-Type: application/json' \ --data-raw '{ "key": "merchantPrivateKey.merchantPublicKey" }' ``` {% endtab %} {% endtabs %} # Error Handling ### Http Response Code | Code | Description | | ----------------------------------- | ------------------------------------------------------------------------ | | 200 - Ok | Everything worked as expected. | | 400 - Bad request | The request was unacceptable, often due to missing a required parameter. | | 401 - Invalid merchant key provided | No valid API key provided. | | 402 - Request failed | The parameters were valid but the request failed. | | 404 - Not found | The requested resource is not found. | | 500-504 - Internal Server Error | Something went wrong on Seerbit's end. | # Payment {% tabs %} {% tab title="cURL" %} ```json curl --location 'https://seerbitapi.com/api/v2/payments' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \ --data-raw '{ "publicKey": "YOUR_PUBLIC_KEY", "amount": "500", "currency": "NGN", "country": "NG", "paymentReference": "payment_reference", "email": "ts@emaildomain.com", "fullName": "Halil TS", "tokenize": "false", "callbackUrl": "https://seerbit.com" }' ``` {% endtab %} {% endtabs %} `POST` `https://seerbitapi.com/api/v2/payments` #### Request Body | Name | Type | Description | | -------------------------------------------------- | ------ | ----------------------------------------------------------------------------- | | publicKey\* | String | This is the merchant public key. | | amount\* | String | This is the amount to be paid. | | email\* | String | This is the email of the customer. | | country\* | String | This is the country from which the transaction is been carried out from | | paymentReference\* | String | This is the unique identifier for a transaction, to be generated by merchant. | {% tabs %} {% tab title="200: OK Successful" %} ```javascript { "status": "SUCCESS", "data": { "code": "00", "payments": { "redirectLink": "http://checkout.seerbitapi.com/#/?mid=merchantpublickey&paymentReference=643108207792124616573324", "paymentStatus": "08" }, "message": "Successful" } } ``` {% endtab %} {% tab title="409: Conflict Transaction Exists" %} ```javascript { "message": "Transaction Exists", "error": "PROCESSING" } ``` {% endtab %} {% endtabs %} # Invoices The invoice API allows you to create, send and manage invoices sent. {% content-ref url="/pages/EsVgQZMHXfXZwXM2QnYN" %} [Create Invoice](/api-endpoints/invoices/create-invoice) {% endcontent-ref %} {% content-ref url="/pages/vHsk2dcklUaGXcqlvBCH" %} [Re-send Invoice](/api-endpoints/invoices/re-send-invoice) {% endcontent-ref %} {% content-ref url="/pages/IWHggNOKCTt0QCS1YV6K" %} [Get Invoice - customerEmail](/api-endpoints/invoices/get-invoice-customeremail) {% endcontent-ref %} {% content-ref url="/pages/dbOnV7cDywAvveA6ES6b" %} [Get Invoice - invoiceNo](/api-endpoints/invoices/get-invoice-invoiceno) {% endcontent-ref %} {% content-ref url="/pages/Hdw1QhWKGfbQfUDfpg5p" %} [Get Invoice - orderNo](/api-endpoints/invoices/get-invoice-orderno) {% endcontent-ref %} # Create Invoice Create and send invoice to customer's emails ## /create `POST` `https://seerbitapi.com/invoice/create` This endpoint allows you to create and send an invoice to a customers email #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------ | | Authorization\* | String | Bearer Token | #### Request Body | Name | Type | Description | | ----------------------------------------------- | ------ | ----------------------------------- | | publickey\* | String | merchant public key | | orderNo\* | String | | | dueDate\* | String | expiration date for invoice payment | | currency\* | String | currency for invoice | | receiversName\* | String | customer name | | customerEmail\* | String | customer email | | itemName\* | String | item invoiced | | Quantity\* | String | no of items | | Rate\* | String | unit price of item | | tax\* | String | tax | {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/create' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \ --data-raw '{ "publicKey":"YOUR_PUBLIC_KEY", "orderNo": "333333221321", "dueDate": "2022-10-23", "currency": "NGN", "receiversName": "Jane Smith", "customerEmail": "janesmith@emaildomain.com", "invoiceItems": [ { "itemName": "Bluetooth Pods", "quantity": 1, "rate": 25000, "tax": 7.5 }, { "itemName": "Quest 10", "quantity": 4, "rate": 100000, "tax": 7.5 } ] }' ``` {% endtab %} {% tab title="201: Created Invoice created successfully" %} ```javascript { "message": "Invoice created successfully ", "payload": { "InvoiceID": 92, "InvoiceNo": "SBT-INV-000092" }, "code": "00" } ``` {% endtab %} {% endtabs %} # Re-send Invoice Resend an invoice to a customer ## /send/invoiceNo `GET` `https://seerbitapi.com/invoice/{{publicKey}}/send/{{InvoiceNo}}` This endpoint allows you to resend an invoice to a customer #### Path Parameters | Name | Type | Description | | ------------------------------------------- | ------ | ------------------- | | InvocieNo\* | String | invoice number | | publicKey | String | merchant public key | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------ | | Authorization\* | String | Bearer token | {% tabs %} {% tab title="201: Created Invoice has been sent successfully" %} ```javascript { "message": "Invoice has been sent successfully", "code": "00" } ``` {% endtab %} {% endtabs %} # Get Invoice - customerEmail Fetch Invoice using customer's email ## /customer/customerEmail `GET` `https://seerbitapi.com/invoice/{{publicKey}}/customer/{{customerEmail}}` This endpoint allows you to fetch a list of invoice available to a customer #### Path Parameters | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------- | | customerEmail\* | String | customer email | | publicKey | String | merchant public key | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------ | | Authorization\* | String | Bearer token | {% tabs %} {% tab title="200: OK successful" %} ```javascript { "payload": [ { "invoiceId": 66, "invoiceNo": "SBT-INV-000066", "totalAmount": 529.75, "subTotal": 500.00, "tax": 29.75, "dueDate": "2022-10-22", "currency": "NGN", "invoiceItems": [ { "itemName": "Bag", "unitPrice": 100, "vat": 5.95, "amount": 100, "quantity": 4 }, { "itemName": "Bag", "unitPrice": 400, "vat": 23.80, "amount": 400, "quantity": 4 } ], "customer": { "externalIdentify": "289276", "businessName": "Jane Smith Ent", "customerName": "Jane Smith", "customerEmail": "js@emaildomian.com", "businessId": "00000051", "id": 19 }, "billingCycle": false, "payButtonOnInvoices": false, "enableAdvancedOptions": false, "partialPayment": false, "status": "DRAFT", "createdAt": "2022-10-18T17:23:13.259" }, { "invoiceId": 67, "invoiceNo": "SBT-INV-000067", "totalAmount": 529.75, "subTotal": 500.00, "tax": 29.75, "dueDate": "2022-10-23", "currency": "NGN", "invoiceItems": [ { "itemName": "Bag", "unitPrice": 100.00, "vat": 5.95, "amount": 100.00, "quantity": 4 }, { "itemName": "Bag", "unitPrice": 400.00, "vat": 23.80, "amount": 400.00, "quantity": 4 } ], "code": "00" } ``` {% endtab %} {% endtabs %} ## /customer/customerEmail `GET` `https://seerbitapi.com/invoice/{{publicKey}}/customer/{{customerEmail}}` #### Path Parameters | Name | Type | Description | | ----------------------------------------------- | ------ | ------------ | | customerEmail\* | String | 8xMKC83iKpLI | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------ | | Authorization\* | String | yJunjDFJ1GIr | {% tabs %} {% tab title="200: OK successful" %} {% endtab %} {% endtabs %} # Get Invoice - invoiceNo Fetch Invoice with invoiceNo ## /invoiceNo `GET` `https://seerbitapi.com/invoice/{{publicKey}}/{{InvoiceNo}}` This endpoint allows you to fetch an invoice using invoiceNo #### Path Parameters | Name | Type | Description | | ------------------------------------------- | ------ | ------------------- | | InvoiceNo\* | String | customer email | | publicKey | String | merchant public key | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------ | | Authorization\* | String | Bearer token | {% tabs %} {% tab title="200: OK Successful" %} ```javascript { "payload": { "invoiceId": 54, "invoiceNo": "SBT-INV-000054", "totalAmount": 556.00, "subTotal": 556.00, "externalBusiness_id": "00000051", "discount": 0.00, "dueDate": "2022-10-12", "currency": "NGN", "invoiceItems": [ { "itemName": "Ada Ada iyoo", "unitPrice": 556.00, "vat": 0.00, "amount": 556.00, "quantity": 278 } ], "customer": {}, "billingCycle": false, "payButtonOnInvoices": false, "enableAdvancedOptions": false, "partialPayment": false, "status": "DRAFT", "createdAt": "2022-10-12T10:27:45.732" }, "code": "00" } ``` {% endtab %} {% endtabs %} # Get Invoice - orderNo Fetch invoice with order no ## /order/orderNo `GET` `https://seerbitapi.com/invoice/{{publicKey}}/order/{{orderNo}}` This endpoint allows you to fetch an invoice using orderNo #### Path Parameters | Name | Type | Description | | ----------------------------------------- | ------ | ------------------- | | orderNo\* | String | orderNo | | public Key | String | merchant public key | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------ | | Authorization\* | String | Bearer token | {% tabs %} {% tab title="200: OK successful" %} ```javascript { "payload": { "invoiceId": 54, "invoiceNo": "SBT-INV-000054", "totalAmount": 556.00, "subTotal": 556.00, "externalBusiness_id": "00000051", "publicKey": "SBPUBK_TCDUH6MNIDLHMJXJEJLBO6ZU2RNUUPHI", "testKey": "SBTESTPUBK_4v0JR58modUFJjF1Es206pveBQjOLxe2", "supportEmail": "ts@greentechng.com", "customerEmail": "qwertypoiuy@mailinator.com", "businessName": "Green Technological Concepts", "discount": 0.00, "dueDate": "2022-10-12", "currency": "NGN", "invoiceItems": [ { "itemName": "Ada Ada iyoo", "unitPrice": 556.00, "vat": 0.00, "amount": 556.00, "quantity": 278 } ], "customer": {}, "billingCycle": false, "payButtonOnInvoices": false, "enableAdvancedOptions": false, "partialPayment": false, "status": "DRAFT", "createdAt": "2022-10-12T10:27:45.732" }, "code": "00" } ``` {% endtab %} {% endtabs %} # Payment Link {% content-ref url="/pages/K9kDRU0nPUoIxAKS6zIc" %} [Create Link](/api-endpoints/payment-link/create-link) {% endcontent-ref %} {% content-ref url="/pages/61KUSgtNGY2zn0D39VVj" %} [Get Link](/api-endpoints/payment-link/get-link) {% endcontent-ref %} {% content-ref url="/pages/VNfVx28sNNbuR8rOdlU2" %} [Update Link](/api-endpoints/payment-link/update-link) {% endcontent-ref %} {% content-ref url="/pages/9xNtDEFwqSbqwgxMjvb2" %} [Delete Link](/api-endpoints/payment-link/delete-link) {% endcontent-ref %} # Create Link Create new payment link to receive payments ## /payLinks/api `POST` `https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api` This enpoint allows you create payment links #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------ | | Authorization\* | String | Bearer Token | #### Request Body | Name | Type | Description | | -------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Status\* | String | link status - (ACTIVE, INACTIVE) | | paymentLinkName\* | String | name of the link | | description\* | String | decription of this page | | currency\* | String | The transaction currency (NGN, GHS, KES,XOF or USD). Country Default currency must be passed | | successMessage | String | Custom message to show customers after a successful payment | | publicKey\* | String | merchant publickey | | customisationName | String | unique url extension for payment link | | paymentFrequency\* | String | ONE-TIME or RECURRENT | | paymentReference | String | | | email | String | | | additionalData | String | additional data for payments | | linkExpirable\* | String | set true or false | | expiryDate | String | set date | | oneTime\* | String | set true if you want the link to be used once or set false if you want the link to be used multiple times | | address | String | true or false if you need to collect customer address | | amount\* | String | true or false | | customerName\* | String | true | | mobileNumber\* | String | true or false if you need to collect customer number | | invoiceNumber | String | true or false if you need to collect invoice number | {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \ --data-raw '{ "status":"ACTIVE", "paymentLinkName": "Donations", "description":"Give out donations", "currency": "NGN", "successMessage":"Thank you for your payment", "publicKey":"YOUR_PUBLIC_KEY", "customizationName":"testing1", "paymentFrequency":"ONE_TIME", "paymentReference": "", "email":"js@emaildomain.com", "requiredFields": { "address":true, "amount":true, "customerName":false, "mobileNumber":true, "invoiceNumber":false }, "additionalData":"Customer Email: js@mailinator.com", "linkExpirable":false, "expiryDate":"", "oneTime":false }' ``` {% endtab %} {% tab title="200: OK Link Successfully Created" %} ```javascript { "data": { "paymentLinks": { "publicKey": "SBPUBK_******************PHI", "status": "ACTIVE", "additionalData": "custom1:null||custom2:null||custom3:null", "paymentLinkName": "Donationas", "description": "Donation", "successMessage": "Payment made successfully!", "paymentLinkId": "000000000", "currency": "NGN", "paymentReference": "" // optional, "paymentFrequency": "RECURRENT", "paymentLinkUrl": "https://pay.seerbitapi.com/paymentLinkId", "customizationName": "utbesti22", "environment": "LIVE", "requiredFields": { "address": true, "amount": true, "customerName": true, "mobileNumber": true, "invoiceNumber": false }, "expiryDuration": 0, "linkExpirable": false, "createdAt": "2021-09-21T10:49:17.728", "updatedAt": "2021-09-21T10:49:17.728", "oneTime": false, "splitPayment": false } } } ``` {% endtab %} {% endtabs %} # Get Link Fetch a list of created payment links ## /payLinks/api/publicKey `GET` `https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api/publicKey` This enpoint allows you to fetch a paymentlink created using merchant publickey #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------ | | Authorization\* | String | Bearer Token | #### Request Body | Name | Type | Description | | -------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Status\* | String | link status - (ACTIVE, INACTIVE) | | paymentLinkName\* | String | name of the link | | description\* | String | decription of this page | | currency\* | String | The transaction currency (NGN, GHS, KES,XOF or USD). Country Default currency must be passed | | successMessage | String | Custom message to show customers after a successful payment | | publicKey\* | String | merchant publickey | | customisationName | String | unique url extension for payment link | | paymentFrequency\* | String | ONE-TIME or RECURRENT | | paymentReference | String | | | email | String | | | additionalData | String | additional data for payments | | linkExpirable\* | String | set true or false | | expiryDate | String | set date | | oneTime\* | String | set true if you want the link to be used once or set false if you want the link to be used multiple times | | amount\* | String | true or false | | customerName\* | String | true | | mobileNumber\* | String | true or false if you need to collect customer number | {% tabs %} {% tab title="200: OK Sucessfull" %} ```javascript { "currentPage": 0, "responseCode": "00", "payload": [ { "businessId": "00000051", "publicKey": "publickey", "status": "ACTIVE", "amount": 10000.00, "customisationName": "SeerBitPay", "additionalData": "", "paymentLinkName": "SeerBit Payment Link", "description": "Buy Items", "paymentLinkId": "00000000", "paymentFrequency": "ONE_TIME", "paymentLinkUrl": "https://pay.seerbitapi.com/paymentLinkID", "pocketReference": "", "environment": "LIVE", "requiredFields": { "address": true, "amount": false, "customerName": true, "mobileNumber": false, "invoiceNumber": false }, "expiryDuration": 0, "linkExpirable": false, "customTime": "", "createdAt": "2021-07-17T12:05:55", "updatedAt": "2021-07-17T12:05:55", "oneTime": false, "splitPayment": false } ], "responseMessage": "successful" } ``` {% endtab %} {% endtabs %} # Update Link Update information for an existing payment link ## /payLinks/api/ `PUT` `https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api` This enpoint allows you to update a created paymentlink #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------ | | Authorization\* | String | Bearer Token | #### Request Body | Name | Type | Description | | -------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Status\* | String | link status - (ACTIVE, INACTIVE) | | paymentLinkName\* | String | name of the link | | description\* | String | decription of this page | | currency\* | String | The transaction currency (NGN, GHS, KES,XOF or USD). Country Default currency must be passed | | successMessage | String | Custom message to show customers after a successful payment | | publicKey\* | String | merchant publickey | | customisationName | String | unique url extension for payment link | | paymentFrequency\* | String | ONE-TIME or RECURRENT | | paymentReference | String | | | email | String | | | additionalData | String | additional data for payments | | linkExpirable\* | String | set true or false | | expiryDate | String | set date | | oneTime\* | String | set true if you want the link to be used once or set false if you want the link to be used multiple times | | amount\* | String | true or false | | customerName\* | String | true | | mobileNumber\* | String | true or false if you need to collect customer number | {% tabs %} {% tab title="cURL" %} 
curl --location --request PUT 'https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \
--data-raw '{
    "paymentLinkId":"0000000",
    "status":"INACTIVE",
    "description":"Test paymentLink",
    "successMessage":"Payment made successfully!",
    "businessName":"My Business",
    "publicKey":"publickKey",
      "customizationName":"my_link_3",
      "paymentFrequency":"RECURRENT",
      "email":"customer@seerbit.com",
      "requiredFields": {
          "address":true,
          "amount":true,
          "customerName":true,
          "mobileNumber":true,
          "invoiceNumber":false
      },
      "linkExpirable":false,
      "expiryDate":"",
      "oneTime":false
  
}'
{% endtab %} {% tab title="200: OK Sucessfull" %} ```javascript { "data": { "paymentLinks": { "publicKey": "PublicKey", "status": "INACTIVE", "description": "Test paymentLink", "successMessage": "Payment made successfully!", "paymentLinkId": "0000000", "paymentFrequency": "RECURRENT", "paymentLinkUrl": "null/my_link_3", "customizationName": "my_link_3", "environment": "LIVE", "requiredFields": { "address": true, "amount": true, "customerName": true, "mobileNumber": true, "invoiceNumber": false }, "expiryDuration": 0, "linkExpirable": false, "updatedAt": "2021-09-21T11:12:57.404", "oneTime": false, "splitPayment": false } } } ``` {% endtab %} {% endtabs %} # Delete Link Delete a specific payment link ## /payLinks/api/deleteLink/paymentLinkId `PUT` `https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api/deleteLink/paymentLinkId` This enpoint allows you to delete a created paymentlink #### Path Parameters | Name | Type | Description | | ----------------------------------------------- | ------ | --------------- | | paymentLinkId\* | String | payment link ID | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------ | | Authorization\* | String | Bearer Token | {% tabs %} {% tab title="200: OK payment link deleted successfully" %} ```javascript { "status": "Deleted" } ``` {% endtab %} {% endtabs %} # Charge Token The charge API allows you charge customers for payments {% content-ref url="/pages/qKEi6a76beBMVUUJeFPy" %} [Create Token](/api-endpoints/charge-token/create-token) {% endcontent-ref %} {% content-ref url="/pages/cdLnWRkvtUYxKMGXJSlX" %} [Get Token](/api-endpoints/charge-token/get-token) {% endcontent-ref %} {% content-ref url="/pages/XWWbDO6OWNbAl0Q4XZQ4" %} [Charge Token](/api-endpoints/charge-token) {% endcontent-ref %} {% content-ref url="/pages/sN1bLRKh7gpMXQZ0qCTg" %} [Bulk Charge](/api-endpoints/charge-token/bulk-charge) {% endcontent-ref %} # Create Token Create and charge card tokens ## /payments/create-token `POST` `https://seerbitapi.com/api/v2/payments/create-token` This endpoint allows you create a token #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------- | | Authorization\* | String | [Bearer Token](/authentication) | #### Request Body | Name | Type | Description | | -------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------- | | publickey\* | String | merchant public key | | amount\* | String | amount to be charged | | fullName\* | String | Customer's fullname | | mobileNumber\* | String | Customer's phone number | | currency\* | String | The transaction currency (NGN, GHS, KES,XOF or USD). Country Default currency must be passed | | country\* | String | country should be set to Country default | | paymentReference\* | String | This is the unique identifier for a transaction, to be generated by merchant. | | email\* | String | customer emails | | paymentType\* | String | paymentType should be set to CARD | | cardNumber\* | String | customer card number | | expiryMonth\* | String | customer card expiry month (e.g 01,02,11) | | expiryYear\* | String | customer card expiry month (e.g 23,24,25) | | cvv\* | String | customer card cvv | | pin\* | String | customer card pin | | redirectUrl\* | String | a page to be redirect to after successful payment | {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/api/v2/payments/create-token' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \ --data-raw '{ "publicKey": "YOUR_PUBLIC_KEY", "amount": "50", "fullName": "Jane Smith", "mobileNumber": "03447522256", "redirectUrl":"http://example.com", "currency": "NGN", "country": "NG", "paymentReference": "204g4de74a7ib0j18dg6bi521aiaejf4", "email": "janesmith@seerbit.com", "paymentType": "CARD", "cardNumber": "512348984984988883", "expiryMonth": "01", "expiryYear": "25", "cvv":"000", "pin":"2222" }' ``` {% endtab %} {% tab title="200: OK Transaction is pending" %} ```javascript { "status": "SUCCESS", "data": { "code": "S20", "message": "Transaction is pending", "payments": { "paymentReference": "{{paymentReference}}", "linkingReference": "SEERBIT60416746746373661414266005", "redirectUrl": "https://seerbitapi.com/50E84E82C25D" } } } ``` {% endtab %} {% endtabs %} # Get Token Fetch details of transaction a transaction to get the authorizationCode for future charges ## /payments/query/{{paymentReference}} `GET` `https://seerbitapi.com/api/v3/payments/query/{{paymentReference}}`\ This endpoint allows you fetch transaction details to get authorizationCode #### Path Parameters | Name | Type | Description | | -------------------------------------------------- | ------ | ----------------------------------------------------------------------------- | | paymentReference\* | String | This is the unique identifier for a transaction, to be generated by merchant. | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------- | | Authorization\* | String | [Bearer Token](/authentication) | {% tabs %} {% tab title="200: OK Transaction is pending" %} ```javascript { "status": "SUCCESS", "data": { "code": "00", "message": "Successful", "payments": { "amount": 50, "mobilenumber": "08387522256", "publicKey": "{{publicKey}}", "paymentType": "CARD", "maskedPan": "5123-40xx-xxxx-0008", "gatewayMessage": "Successful", "gatewayCode": "00", "gatewayref": "SEERBIT674774783883", "businessName": "Green Technological Concepts", "mode": "live", "channelType": "MASTERCARD", "cardBin": "5123", "lastFourDigits": "0008", "country": "NG", "currency": "NGN", "paymentReference": "{{paymentReference}}", "transactionProcessTime": "2022-08-25 08:57:45.634", "reason": "Successful", "authorizationCode": "6636373737222" }, "customers": { "customerId": "SBT56736733yye663737", "customerName": "Jane Smith", "customerMobile": "08387522256", "customerEmail": "seerbit@emaildomain.com" } } } ``` {% endtab %} {% endtabs %} # Charge Token Transactions with authorizationCode can be charged with this endpoint. ## /payments/charge-token `POST` `https://seerbitapi.com/api/v2/payments/charge-token` This endpoint allows you to charge a customer using the authorizationCode #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------- | | Authorization\* | String | [Bearer Token](/authentication) | #### Request Body | Name | Type | Description | | --------------------------------------------------- | ------ | ----------------------------------- | | authorizationCode\* | String | code to charge | | paymentReference\* | String | unique payment reference for charge | | publicKey\* | String | merchant publickey | | amount\* | String | amount you want to charge | {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/api/v2/payments/charge-token' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \ --data '{ "publicKey": "YOUR_PUBLIC_KEY", "amount": "110", "paymentReference": "charge_test_3451", "authorizationCode": "ye773838jje8837abe" }' ``` {% endtab %} {% tab title="200: OK Successful" %} ```javascript { "status": "SUCCESS", "data": { "code": "00", "message": "APPROVED", "payments": { "paymentReference": "9288383999393", "linkingReference": "SEERBIT43376378378377720196" } } } ``` {% endtab %} {% endtabs %} # Bulk Charge Charge multiple payments from your customers ## /payments/bulk-tokenize-charge `POST` `https://seerbitapi.com/api/v2/payments/bulk-tokenize-charge` This endpoint allows you to send an array of authorizationCode and amount so payments are charged in batches #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------- | | Authorization\* | String | [Bearer Token](/authentication) | #### Request Body | Name | Type | Description | | --------------------------------------------------- | ------ | ----------------------------------- | | authorizationCode\* | String | code to charge | | paymentReference\* | String | unique payment reference for charge | | publicKey\* | String | merchant publickey | | amount\* | String | amount you want to charge | {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/api/v2/payments/bulk-tokenize-charge' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \ --data ' [ { "publicKey": "publickKey", "amount": "11", "paymentReference": "reference", "authorizationCode": "authorizationCode" }, { "publicKey": "publickKey", "amount": "11", "paymentReference": "reference", "authorizationCode": "authorizationCode" }, { "publicKey": "publickKey", "amount": "11", "paymentReference": "reference", "authorizationCode": "authorizationCode" }, { "publicKey": "publickKey", "amount": "11", "paymentReference": "reference", "authorizationCode": "authorizationCode" } ]' ``` {% endtab %} {% tab title="200: OK Successful" %} ```javascript { "code": "00", "message": "Successful", "payload": { "batchId": "d4wnvzc" } } ``` {% endtab %} {% endtabs %} # Query Bulk Charge with BacthId Charge multiple payments from your customers ## /payments/bulk-tokenize-charge `GET` `https://seerbitapi.com/api/v2/payments/bulk-tokenize-charge-search?batchId={{batchId}}` This endpoint allows you to send an array of authorizationCode and amount so payments are charged in batches #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------- | | Authorization\* | String | [Bearer Token](/authentication) | #### Request Body | Name | Type | Description | | --------------------------------------------------- | ------ | --------------------------------------------- | | authorizationCode\* | String | code to charge | | batchId\* | String | unique Id to retrieve batched tokenize-charge | | publicKey\* | String | merchant publickey | {% tabs %} {% tab title="200: OK Successful" %} ```javascript { "code": "00", "message": "Successful", "payload": { "content": [ { "id": 7, "authorizationCode": "authocode", "statusCode": "00", "message": "Successful", "createdAt": "2022-10-12T09:58:40.102", "updatedAt": "2022-10-12T09:58:40.102", "batchId": "k2auyutyr", "currency": "NGN", "cardBin": "5123400", "cardLastFourDigits": "0739", "cardType": "VISA", "amount": "10.00" }, { "id": 8, "authorizationCode": "authocode", "statusCode": "00", "message": "Successful", "createdAt": "2022-10-12T09:58:46.443", "updatedAt": "2022-10-12T09:58:46.443", "batchId": "kuiuyu", "currency": "NGN", "cardBin": "5123400", "cardLastFourDigits": "0008", "cardType": "VISA", "amount": "15.00" } ], "pageable": { "sort": { "sorted": true, "unsorted": false, "empty": false }, "pageNumber": 0, "pageSize": 10, "offset": 0, "paged": true, "unpaged": false }, "last": true, "totalElements": 2, "totalPages": 1, "sort": { "sorted": true, "unsorted": false, "empty": false }, "first": true, "numberOfElements": 2, "size": 10, "number": 0, "empty": false } } ``` {% endtab %} {% endtabs %} # Subscriptions Subscription APIs allows you create and management recurring payments {% content-ref url="/pages/mjW1I8kDl0Yc3EbRy6uF" %} [Create Subscription](/api-endpoints/subscriptions/create-subscription) {% endcontent-ref %} {% content-ref url="/pages/2d9YMW7fEIYMVgyjvIen" %} [Charge Subscription](/api-endpoints/subscriptions/charge-subscription) {% endcontent-ref %} {% content-ref url="/pages/kfgfmTJrb099bMndhHMq" %} [Get Customer Subscription](/api-endpoints/subscriptions/get-customer-subscription) {% endcontent-ref %} {% content-ref url="/pages/q57FbtsBQEkoUBxzHwcl" %} [Update Customer Subscription](/api-endpoints/subscriptions/update-customer-subscription) {% endcontent-ref %} {% content-ref url="/pages/HY8QrnWcS30lYAaLWDkN" %} [Get Merchant Subscription](/api-endpoints/subscriptions/get-merchant-subscription) {% endcontent-ref %} # Create Subscription You can create a plan by calling the Create Plan endpoint or you can do this directly from the SeerBit Merchant Dashboard `/recurrent/plan/create` `POST` `https://merchants.seerbitapi.com/api/v1/recurrent/plan/create` #### Headers | Name | Type | Description | | ------------- | ------ | ------------ | | Authorization | String | Bearer Token | #### Request Body | Name | Type | Description | | ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | publicKey\* | String | This is the merchant public key. | | amount\* | String | This is the amount to be paid. | | email\* | String | This is the email of the customer. | | country\* | String | This is the country from which the transaction is been carried out from | | paymentReference\* | String | This is the unique identifier for a transaction, to be generated by merchant. | | planId | String | the planId represents a product of the merchant that the customer wants to pay for e.g DSTV bouqet. | | CardNumber\* | String | this is the name of the cardholder | | expiryYear\* | String | this is the card's expiry year | | expiryMonth\* | String | this is the card's expiry month | | cvv\* | String | this is the 3 digit code behind the debit card | | productDescription\* | String | this is the product description supplied by the merchant | | billingCycle\* | String | this is the rate of reoccurrence of the charge to the tokenized card | | subscriptionAmount\* | boolean | this is passed as true if the subscription amount is to be charged at the point of creating subscription. It is passed as false if the default amount of SeerBit is to be charged at the point of creating subscription. | | mobileNumber\* | String | customer's number | | customerId | String | | | billingPeriod\* | String | this is the number of times seerBit will do a recurrent billing | | redirectUrl\* | String | this is returned when the payment link service is called | {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://merchants.seerbitapi.com/api/v1/recurrent/plan/create' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer Token\ --data '{ "productId": "", "productDescription": "", "amount": "100", "billingCycle": "HOURLY", "limit": 5, "publicKey": "", "country": "NG", "currency": "NGN", "allowPartialDebit": false }' ``` {% endtab %} {% tab title="200: OK Successful" %} ```javascript { "payload": { "country": "NG", "createdAt": 1715607343498, "amount": 100, "productId": "", "billingCycle": "HOURLY", "currency": "NGN", "payUrl": "https://pay.seerbitapi.com/db1ea861993689a57dac", "details": { "country": "NG", "amount": 100, "productId": "", "allowPartialDebit": false, "payLinkUrl": "https://pay.seerbitapi.com/db1ea861993689a57dac", "publicKey": "", "createdAt": 1715607343498, "trialDuration": 0, "trialPeriod": false, "billingCycle": "HOURLY", "limit": 5, "planId": "db1ea861993689a57dac", "currency": "NGN", "id": 20031, "productDescription": "", "updatedAt": null, "status": "ACTIVE" }, "publicKey": "", "plan": "db1ea861993689a57dac", "productDescription": "" }, "message": "Successful", "status": "SUCCESS", "responseCode": "00" } ``` {% endtab %} {% tab title="401: Unauthorized Invalid Authentication Token" %} ```javascript { "message": "Invalid Authentication Token", "error": "INPUT" } ``` {% endtab %} {% tab title="400: Bad Request Bad Request" %} ```javascript { "message": "Bad Request", "error": "There has been a problem with reading or understanding the request." } ``` {% endtab %} {% endtabs %} # Charge Subscription The code snippet below shows an example request for charging a customer with an authorizationCode ## /recurring/charge `POST` `https://seerbitapi.com/api/v2/recurring/charge` #### Headers | Name | Type | Description | | ------------- | ------ | ------------ | | Authorization | String | Bearer Token | #### Request Body | Name | Type | Description | | ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | publicKey\* | String | This is the merchant public key. | | amount\* | String | This is the amount to be paid. | | email\* | String | This is the email of the customer. | | country\* | String | This is the country from which the transaction is been carried out from | | paymentReference\* | String | This is the unique identifier for a transaction, to be generated by merchant. | | planId | String | the planId represents a product of the merchant that the customer wants to pay for e.g DSTV bouqet. | | CardNumber\* | String | this is the name of the cardholder | | expiryYear\* | String | this is the card's expiry year | | expiryMonth\* | String | this is the card's expiry month | | cvv\* | String | this is the 3 digit code behind the debit card | | productDescription\* | String | this is the product description supplied by the merchant | | billingCycle\* | String | this is the rate of reoccurrence of the charge to the tokenized card | | subscriptionAmount\* | boolean | this is passed as true if the subscription amount is to be charged at the point of creating subscription. It is passed as false if the default amount of SeerBit is to be charged at the point of creating subscription. | | mobileNumber\* | String | customer's number | | customerId | String | | | billingPeriod\* | String | this is the number of times seerBit will do a recurrent billing | | redirectUrl\* | String | this is returned when the payment link service is called | {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/api/v2/recurring/charge' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \ --data-raw '{ "amount":"200", "publicKey":"YOUR_PUBLIC_KEY", "email":"js@emaildomain.com", "allowPartialDebit":"true", "authorizationCode":"1234567898765325", "paymentReference":"2938765582R37065687631", "currency":"NGN" }' ``` {% endtab %} {% tab title="200: OK Successful" %} ```javascript { "status": "SUCCESS", "data": { "code": "00", "payments": { "code": "00", "message": "Successful", "paymentReference": "2938765582R37065687631", "publicKey": "SBTEST**************************viTF", "amount": "200", "currency": "NGN", "country": "NG", "email": "js@emaildomain.com", "productDescription": "Authorised charge" }, "message": "Successful" } } ``` {% endtab %} {% tab title="401: Unauthorized Invalid Authentication Token" %} ```javascript { "message": "Invalid Authentication Token", "error": "INPUT" } ``` {% endtab %} {% tab title="400: Bad Request Bad Request" %} ```javascript { "message": "Bad Request", "error": "There has been a problem with reading or understanding the request." } ``` {% endtab %} {% endtabs %} # Get Customer Subscription The code snippet below shows an example response to get customer subscription by customerId `GET``https://seerbitapi.com/api/v2/recurring/{publicKey}/customerId/{customerId}` {% tabs %} {% tab title="200: OK Successful" %} ```javascript { "status": "SUCCESS", "data": { "subscriptions": [ { "publicKey": "SBTEST**************************viTF", "amount": "100", "country": "NG", "customerId": "ba981a0b7ed1c68ad245", "cardName": "Jane Smith", "cardNumber": "5123-45xx-xxxx-0008", "plan": "ead5e697f42c1cd60813", "status": "ACTIVE", "billingId": "PUBK_PjQ5d1578649732262", "authorizationCode": "145a3bb3418824c14d65", "startDate": "2020-10-01 10:47:49", "createdAt": 1578649752000 }, { "publicKey": "SBTEST**************************viTF", "amount": "20000", "country": "NG", "customerId": "ba981a0b7ed1c68ad245", "cardName": "John Smith", "cardNumber": "5123-45xx-xxxx-0008", "plan": "80b0854b35a0e279efc3", "status": "INACTIVE", "billingId": "PUBK_PjQ5d1578650322483", "authorizationCode": "ddfce36aa4f3abc7cf72", "startDate": "2020-10-01 10:58:25", "createdAt": 1578650353000 } ], "code": "00", } ``` {% endtab %} {% endtabs %} # Update Customer Subscription The code snippet below shows an example request for updating a subscription `POST` `https://seerbitapi.com/eactrecurrent/updates` {% tabs %} {% tab title="cURL" %} ```javascript curl --location --request PUT 'https://seerbitapi.com/api/v2/recurring/updates' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \ --data '{ "amount":"20000", "currency":"NGN", "country":"NG", "mobileNumber":"08033456500", "billingId":"PUBK_PjQ5d1578650322483", "publicKey":"YOUR_PULIC_KEY", "status":"INACTIVE" }' ``` {% endtab %} {% tab title="200: OK Successful" %} ```javascript "status": "SUCCESS", "data": { "subscriptions": { "publicKey": "SBTEST**************************viTF", "amount": "20000", "country": "NG", "customerId": "ba981a0b7ed1c68ad245", "cardName": "Jane Smith", "cardNumber": "5123-45xx-xxxx-0008", "plan": "80b0854b35a0e279efc3", "status": "INACTIVE", "billingId": "PUBK_PjQ5d1578650322483", "authorizationCode": "ddfce36aa4f3abc7cf72", "startDate": "2020-10-01 10:58:25", "createdAt": 1578650353000 }, "code": "00", "message": "Successful" } ``` {% endtab %} {% endtabs %} # Get Merchant Subscription The Get Merchant Subscription returns all customer subscriptions. Included in the response is authorizationCode which can be used for separate charges to the customer `GET` `https://seerbitapi.com/api/v2/recurring/publicKey/{{publiKey}}` {% tabs %} {% tab title="200: OK Successful" %} ```javascript { "status": "SUCCESS", "data": { "subscriptions": [ { "publicKey": "SBTEST**************************viTF", "amount": "20", "country": "NG", "customerId": "651d33a62ad69c9f37c4", "cardName": "Jane Smith", "cardNumber": "2223-00xx-xxxx-0007", "plan": "ae702f51220000722dca", "status": "ACTIVE", "billingId": "WQ6676yPOpr12348o", "authorizationCode": "2beb0ccdd347e604552a", "startDate": "2019-01-11 00:00:00", "createdAt": 1578648329000 }, { "publicKey":"SBTEST**************************viTF", "amount": "100", "country": "NG", "customerId": "ba981a0b7ed1c68ad245", "cardName": "Jane Smith", "cardNumber": "5123-45xx-xxxx-0008", "plan": "ead5e697f42c1cd60813", "status": "ACTIVE", "billingId": "PUBK_PjQ5d1578649732262", "authorizationCode": "145a3bb3418824c14d65", "startDate": "2020-10-01 10:47:49", "createdAt": 1578649752000 } ], "code": "00", "message": "successful" } } ``` {% endtab %} {% endtabs %} # Virtual Account The Virtual Account API allows you to create and manage Virtual Accounts {% hint style="info" %} This feature is only available to businesses in Nigeria. {% endhint %} {% content-ref url="/pages/AAT9shZH1hoiK3nkI776" %} [Create Virtual Account](/api-endpoints/virtual-account/create-virtual-account) {% endcontent-ref %} {% content-ref url="/pages/XuJuWmCsrU8HFuiVxuDK" %} [Get Virtual Account](/api-endpoints/virtual-account/get-virtual-account) {% endcontent-ref %} {% content-ref url="/pages/utiMeervZWwctELyKX1Y" %} [Delete Virtual Account](/api-endpoints/virtual-account/delete-virtual-account) {% endcontent-ref %} # Create Virtual Account Create a virtual accounts your customers to make payments ## /vitrual-accounts `POST` `https://seerbitapi.com/api/v2/virtual-accounts` This endpoint allows you to create virtual account numbers #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------ | | authorization\* | String | Bearer token | #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | ------------------------------------------------ | | publicKey\* | String | merchant public key | | fullName\* | String | name to be on the account number | | bankVerificationNumber | String | owners BVN to match fullName | | currency\* | String | currency to be set to NGN | | reference\* | String | unique reference to identify the virtual account | | email | String | owners email | {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/api/v2/virtual-accounts' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \ --data-raw '{ "publicKey": "YOUR_PUBLIC_KEY", "fullName": "Jane Smith", "bankVerificationNumber":"", "currency": "NGN", "country": "NG", "reference": "FIRST_VIRTUAl_17", "email": "js@emaildomain.com" }' ``` {% endtab %} {% tab title="201: Created Success" %} ```javascript { "status": "SUCCESS", "data": { "code": "S20", "payments": { "reference": "FIRST_VIRTUAl_7", "walletName": "SEERBIT(Business Name)", "bankName": " 9PAYMENT SERVICE BANK", "accountNumber": "Account Number" }, "message": "Account created " } } ``` {% endtab %} {% endtabs %} # Get Virtual Account Fetch a virtual account using reference /vitrual-accounts/reference `GET` `https://seerbitapi.com/api/v2/virtual-accounts/{{paymentreference}}` This endpoint allows you to fetch a virtual account using the unique reference #### Path Parameters | Name | Type | Description | | ------------------------------------------- | ------ | ------------------------------------------------ | | reference\* | String | unique reference to identify the virtual account | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------ | | authorization\* | String | Bearer token | {% tabs %} {% tab title="201: Created Success" %} ```javascript { "status": "SUCCESS", "data": { "code": "00", "payments": { "reference": "VA_1", // virtual account reference "linkingReference": "9PSB641860391656618499020", "walletName": "SEERBIT(Business Name)", "wallet": "Account Number", "bankName": "_9PAYMENT_SERVICE_BANK", "accountNumber": "Account Number" }, "message": "" } } ``` {% endtab %} {% endtabs %} # Delete Virtual Account Delete a virtual account ## /vitrual-accounts/reference `DELETE` `https://seerbitapi.com/api/v2/virtual-accounts/{{reference}}` This endpoint allows you to delete a virtual account using the unique reference #### Path Parameters | Name | Type | Description | | ------------------------------------------- | ------ | ------------------------------------------------ | | reference\* | String | unique reference to identify the virtual account | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------ | | authorization\* | String | Bearer token | {% tabs %} {% tab title="201: Created Virtual account has been deleted" %} ```javascript { "status": "SUCCESS", "data": { "code": "00", "message": "Virtual account has been deleted" } } ``` {% endtab %} {% endtabs %} # Get Payment The code snippet below shows an example response to get payments `GET` `https://seerbitapi.com/api/v2/virtual-accounts/{{reference}}` {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/api/v2/virtual-accounts/YOUR_PUBLIC_KEKY/{{accountNumber}}' \ --header 'Authorization: Bearer YOUR_ENCRYPTION_KEY' ``` {% endtab %} {% tab title="200: OK Successful" %} ```javascript { "status": "SUCCESS", "data": { "code": "00", "payload": [ { "id": 14705414, "fullName": "Customer Name", "publicKey": "YOUR_PUBLIC_KEY", "processor": "_9PAYMENT_SERVICE_BANK", "paymentType": "TRANSFER", "shopperReference": null, "amount": 100.0, "productId": null, "productDescription": null, "email": "customeremail@gmail.com", "quantity": null, "maskedPan": null, "gateway": "_9PAYMENT_SERVICE_BANK", "gatewayMessage": "Successful", "gatewayCode": "00", "transactionRef": "GT-01", "gatewayRef": "100004230627104826104793084015", "businessName": "Business Name", "fee": null, "mode": "LIVE", "callbackUrl": null, "redirectUrl": null, "channelType": "transfer", "paymentKey": null, "sourceIP": null, "deviceType": null, "clientAppCode": null, "cardBin": null, "lastFourDigits": null, "type": null, "linkingreference": null, "country": "NG", "currency": "NGN", "smsProvider": null, "customerId": null, "internalreference": "_SBT_N7N7EU523C", "accountNumber": "customer account number", "narration": null, "creditAccountName": "Seerbit(Tola Sambo)", "transferType": "RESERVE_ACCOUNT", "paymentReference": "GT-01_SBT_N7N7EU523C", "batchId": null, "sessionId": null, "bankName": "", "creditAccountNumber": "4015310501", "bankCode": null, "alternatePaymentReference": null, "settlementCode": "00", "settlementMessage": "Push Successful", "settlementTime": "2023-06-27 11:49:37", "orderStatusCode": null, "orderStatusMessage": null, "status": "PUSHED", "mobileNumber": "404", "dateOfBirth": null, "branchPhoneNumber": null, "transferedAmount": 100.0, "scheduleId": null, "isCardInternational": "LOCAL", "reason": "Successful", "retry": false, "metaData": null, "event": [], "order": [], "createdAt": "2023-06-27T10:49:28.000+0000", "updatedAt": "2023-06-27T10:49:28.000+0000", "cardName": null, "isNigeriancard": null, "cardCountry": null, "intCurrency": null, "rate": null, "inCardProcessingFee": null, "intAmountCharge": null, "processorCode": "00", "processorMessage": "Successful", "invoiceNumber": null, "billId": null, "locationPhoneNumber": null, "pocketReferenceId": null, "transferAccountType": "STATIC", "bearer": "MERCHANT", "transLink": null, "vendorId": null, "payLinkEnvironment": null, "payLinkStatus": null, "payLinkAmount": null, "payLinkAdditionalData": null, "payLinkName": null, "payLinkDescription": null, "payLinkRedirectUrl": null, "payLinkSuccessMessage": null, "paymentLinkId": null, "payLinkCustomizationName": null, "payLinkFrequency": null, "payLinkIsOneTimeUse": false, "terminalId": null, "stan": null, "transactionComplete": null, "cardExpiryMonth": null, "cardExpiryYear": null, "tokenize": false } ], "message": "successful" } } ``` {% endtab %} {% endtabs %} # Pay with Transfer Accepts payments from your customers through transfer. This method is available for Nigerian customers only `POST` `https://seerbitapi.com/api/v2/payments/initiates` #### How it works 1. To initiate a pay with transfer, make a request to the transfer payments service with the `payments/initiates` endpoint. 2. When the request is made you are expected to get a response with a bank account number for transfer to be made. 3. Customer completes the transaction using by transferring to the generated account number. 4. Verify the payment {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/api/v2/payments/initiates' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTION_KEY' \ --data-raw '{ "publicKey":"YOUR_PUBLIC KEY", "amount":"100", "fullName": "Jane Doe", "mobileNumber": "0887522256", "email":"youremail@domain.com", "currency": "NGN", "country": "NG", "paymentReference": "dsffererer", "callbackUrl": "http://checkout-seerbit.surge.sh", "redirectUrl": "http://checkout-seerbit.surge.sh", "paymentType": "TRANSFER" }' ``` {% endtab %} {% tab title="Request" %} ```java { "publicKey":"public key", "amount":"100", "fullName": "Rasaq Agbalaya", "mobileNumber": "08087522256", "email":"rasaq@gmail.com", "currency": "NGN", "country": "NG", "paymentReference": "dsffererer", "callbackUrl": "http://checkout-seerbit.surge.sh", "redirectUrl": "http://checkout-seerbit.surge.sh", "paymentType": "TRANSFER" } ``` {% endtab %} {% tab title="200: OK Successful" %} ```java { "status": "SUCCESS", "data": { "code": "00", "payments": { "paymentReference": "dsfr55266tyt5554y166", "walletName": "SEERBIT(Merchant Name)", "wallet": "9979878249", "bankName": "Providus Bank", "accountNumber": "9979878249" }, "message": "ACCOUNT OPENED SUCCESSFULLY" } } ``` {% endtab %} {% endtabs %} # Pay with USSD ## /payments/initiates `POST` `https://seerbitapi.com/api/v2/payments/initiates` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ---------------- | | authorization\* | String | Bearer Token | | content-type\* | String | application/json | #### Request Body | Name | Type | Description | | -------------------------------------------------- | ------ | ----------------------------------------------------------------------------- | | publicKey\* | String | This is the merchant public key. | | amount\* | String | This is the amount to be paid. | | email\* | String | This is the email of the customer. | | country\* | String | This is the country from which the transaction is been carried out from | | paymentReference\* | String | This is the unique identifier for a transaction, to be generated by merchant. | | mobileNumber\* | String | | | fullName\* | String | | | currency\* | String | | | callbackUrl\* | String | | | redirectUrl\* | String | | | paymentType\* | String | | | bankCode\* | String | | {% tabs %} {% tab title="200: OK Successful" %} ```javascript { "status": "SUCCESS", "data": { "code": null, "payments": { "paymentReference": "dsffererer", "linkingReference": "CSEERBIT724622561618580872054", "providerreference": "8206", "ussdDailCode": "*901*000*8206#" }, "message": null } } ``` {% endtab %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/api/v2/payments/initiates' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTION_KEY' \ --data-raw '{ "publicKey":"YOUR_PUBLIC_KEY", "amount":"100", "fullName": "FirstName LastName", "mobileNumber": "customer mobile number", "email":"firstname@mail.com", "currency": "NGN", "country": "NG", "paymentReference": "dsffererer", "callbackUrl": "http://yourdomain.com", "redirectUrl": "http://yourdomain.com", "paymentType": "USSD", "bankCode":"044" }' ``` {% endtab %} {% endtabs %} # Mobile Money Payments `POST` `https://seerbitapi.com/api/v2/payments/initiates` The code snippet below shows an example request for generating a payment link to complete a payment {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/api/v2/payments/initiates' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTION_KEY' \ --data-raw '{ "fullName":"FirstName LastName", "email":"firstname@mail.com", "mobileNumber":"23309494949498", "publicKey":"merchant_publicKey", "paymentReference": "MOMOTYTSF4VA", "deviceType":"nokia 3310", "sourceIP":"1.0.1.0", "currency": "UGX", "productDescription": "snacks", "country": "UG", "fee": "1.00", "network":"MTN", "voucherCode":"", "amount": "10.01", "paymentType": "MOMO" }' ``` {% endtab %} {% tab title="Response" %} ```javascript { "status": "SUCCESS", "data": { "code": "INP", "payments": { "paymentReference": "O67456S537798799QWEWAT0MPTYP", "linkingReference": "CF323190231596441884237" }, "message": "Kindly Enter Otp" } } ``` {% endtab %} {% endtabs %} # Bank Account Payments `POST` `https://seerbitapi.com/api/v2/payments/initiates` {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/api/v2/payments/initiates' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTION_KEY' \ --data-raw '{ "publicKey":"Your_public_key", "amount":"2000.00", "fee":"10", "fullName":"John Doe", "mobileNumber":"08037456590", "currency":"NGN", "country":"NG", "paymentReference":"UYTRE234566677RDFGFDDSS", "email":"johndoe@gmail.com", "productId":"Foods", "productDescription":"Uba Account Transaction ", "clientAppCode":"kpp64", "redirectUrl":"https://checkout.seerbit.com", }' ``` {% endtab %} {% tab title="Response" %} ```javascript { "status": "SUCCESS", "data": { "code": "S20", "payments": { "paymentReference": "UYTRE234566677RDFGFDDSS", "linkingReference": "F320660611587911267617" }, "message": "Transaction is pending" } } ``` {% endtab %} {% endtabs %} # Card Payment Cards are one of the most popular ways to make payments online with a large global reach. SeerBit supports the most popular card types with a simple implentation.\
**Card Payment Process** 1. Customers enters card details on merchant website. 2. SeerBit checks that the details provided are valid (e.g the expiry date entered is not in the past) 3. Authentication : Some cards may prompt the card holder to enter a pin or a one time password sent to the card holder's phone or email to authenticate the transaction. 4. Authorization : The bank checks for sufficient funds on the card holder's account. if successful the amount is held in the customers account and released to the merchant on capture 5. Capture : The money moves from the card holder's account (issuing bank) to the merchant account immediately after authorization # Initializing a Card Payment `POST` `https://seerbitapi.com/api/v2/payments/initiates` **How it works** 1. Collect the customers details (Fullname, Email and Mobile Number) and Card details. 2. Make a request to the payment service with the payment/initiates endpoint. 3. Based on the cardholders card type the seerBit selects an auth method. {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/api/v2/payments/initiates' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTION_KEY' \ --data-raw '{ "publicKey":"YOUR_PUBLIC_KEY", "amount":"100.00", "fee":"10", "fullName":"John Doe", "mobileNumber":"08032000001", "currency":"NGN", "country":"NG", "paymentReference":"LKJHGFDR123UI23992JN23R", "email":"johndoe@gmail.com", "productId":"Foods", "productDescription":"RASPBERRY", "clientAppCode":"kpp64", "redirectUrl":"", "paymentType":"CARD", "channelType":"Mastercard", "deviceType":"Apple Laptop", "sourceIP":"127.0.0.1:3456", "cardNumber":"12345678900929", "cvv":"123", "expiryMonth":"12", "expiryYear":"26", "pin":"0000", "retry":"false" }' ``` {% endtab %} {% tab title="Response" %} ```javascript { "status": "SUCCESS", "data": { "code": "S20", "payments": { "paymentReference": "LKJHGFDR123UI23992JN23R", "linkingReference": "F468778061587905955047" }, "message": "Kindly enter OTP" } } ``` {% endtab %} {% endtabs %} # Scenario 1 (Verve Card Type) `POST` `https://seerbitapi.com/api/v2/payments/initiates` **Scenario 1 (Verve Card Type)** 1. The customers gets prompted to enter card pin. 2. After the customer enters the card pin, call the payment service again using payment/initiates endpoint. 3. An OTP (one time password) is sent to the cardholders registered phone number or email to validate the transaction. 4. To Validate the transaction Call the Validate OTP payments/otp endpoint with the customers OTP and Pass the transactions linking reference in the request body. {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/api/v2/payments/initiates' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTION_KEY' \ --data '{ "transaction": { "linkingreference":"F468778061587905955047", "otp":"496865" } }' ``` {% endtab %} {% tab title="Response" %} ```javascript { "status": "SUCCESS", "data": { "code": "00", "payments": { "reference": "LKJHGFDR123UI23992JN23R", "linkingreference": "F468778061587905955047" }, "message": "Successful" } } ``` {% endtab %} {% endtabs %} # Scenario 2 (Master Card and Visa Card Type) `POST` `https://seerbitapi.com/api/v2/payments/initiates` **Scenario 2 (Master Card and Visa Card Type)** 1. The occurs for 3D secure card transactions. 2. After the payment has been initiated, the card holder gets prompted to complete the payment on the card's bank page. 3. For a successful initial call, code S20 will be returned with a redirect link in the redirectUrl field, merchant is expected to redirect to the link. Because of this merchant is expected to always pass the redirectUrl link that SeerBit should come back to after the payment is completed on 3Ds site. {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/api/v2/payments/initiates' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTION_KEY' \ --data '{ "transaction": { "linkingreference":"F468778061587905955047", "otp":"496865" } }' ``` {% endtab %} {% tab title="Response" %} ```javascript { "status": "SUCCESS", "data": { "code": "S20", "payments": { "paymentReference": "LKJHGFDR123UI23992JN23R", "linkingReference": "F468778061587905955047", "redirectUrl": "https://seerbitapigateway.com/seerbit/card-dispatch sredref=F468778061587905955047" }, "message": "Transaction is pending" } } ``` {% endtab %} {% endtabs %} # Scenario 3 `POST` `https://seerbitapi.com/api/v2/payments/initiates` **Scenario 3** 1. The customers gets prompted to enter card pin {% tabs %} {% tab title="cURL" %} ```javascript curl --location 'https://seerbitapi.com/api/v2/payments/initiates' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ENCRYPTION_KEY' \ --data '{ "transaction": { "linkingreference":"F468778061587905955047", "otp":"496865" } }' ``` {% endtab %} {% tab title="Response" %} ```javascript { "status": "SUCCESS", "data": { "code": "00", "payments": { "paymentReference": "92SQ2A3BCDE42RFR2AS122221", "linkingReference": "F611305721592735518716" }, "message": "Successful" } } ``` {% endtab %} {% endtabs %}