Standard Payments

Initiate a payment

POST /transaction/initialize

For most use cases, this is where the payment journey begins. Need to collect a payment from a customer? Submit the customer and order details, and we'll return a link to a secure prebuilt payment page hosted on Credo that you can redirect your customer to for them to make payment.

Request Parameters

Param	Required	Description
api-public-key	Yes	Your public key. Use test key for test mode and live key for live mode
email	Yes	Email address of customer
amount	Yes	Amount (in the lowest currency value - kobo, pesewas or cent) you are debiting customer
reference	No	Unique case-sensitive transaction reference. Only alphanumeric characters are allowed. If you do not pass this parameter, Credo will generate a unique reference.
currency	No	Currency charge should be performed. Allowed values are NGN or USD. It defaults to your integration currency.
channels	No	An array of payment channels to control what channels you want to make available to the user to make a payment with. Available channels include; ['card', 'bank']
metadata	No	Object containing any extra information you want to be recorded with the transaction. Fields within the custom_field object will appear on merchant receipts and within the transaction information on the Credo Dashboard.
callbackUrl	No	After a payment attempt, we'll redirect the customer to this URL
serviceCode	No	Dynamic settlement service code
customerFirstName	No	Customer's first name
customerLastName	No	Customer's last name
customerPhoneNumber	No	Customer's phone number
bearer	No	0 = Customer bears fee; 1 = Merchant bears fee

Example requests

JavaScript

const inputBody = {
"amount": 15000,
"bearer": 0,
"callbackUrl": "https://example.com/",
"channels": [“card”, “bank”],
"currency": "NGN",
"customerFirstName": "John",
"customerLastName": "Wick",
"customerPhoneNumber": "2348032132100",
"email": "john.wick@credocentral.com",
"metadata": {
"bankAccount": "0114877128",
"customFields":[ {"variable_name": "gender", "value": "Male", "display_name": "Gender" } ]
},
"//reference": "mTL022NzzQ0 - This must be Unique, if not present we will generate one",
"//serviceCode": "201220045mG7mTL022zQ09 - If you have dynamic settlement service setup"
}
const headers = {
  'Content-Type': 'application/json',
  Accept: 'application/json',
  Authorization: 'Public Key',
}

const url = 'https://api.credocentral.com/transaction/initialize'
fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(inputBody),
})
  .then((res) => res.json())
  .then(console.log)

PHP

<?php

require 'vendor/autoload.php';

$body = [
  'amount' => 15000,
  'bearer' => 0,
  'callbackUrl' => 'https://example.com/',
  'channels' => ['card', 'bank'],
  'currency' => 'NGN',
  'customerFirstName' => 'John',
  'customerLastName' => 'Wick',
  'customerPhoneNumber' => '2348032132100',
  'email' => 'john.wick@credocentral.com',
  'metadata' => [
    'bankAccount' => '0114877128',
    'customFields' => [
      [
        'variable_name' => 'gender',
        'value' => 'Male',
        'display_name' => 'Gender',
      ],
    ],
  ],
  '//reference': 'mTL022NzzQ0 - This must be Unique, if not present we will generate one',
  '//serviceCode': '201220045mG7mTL022zQ09 - If you have dynamic settlement service setup'
];

$headers = [
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Public Key',
];

$client = new \GuzzleHttp\Client();

$response = $client->request(
  'POST',
  'https://api.credocentral.com/transaction/initialize',
  [
    'headers' => $headers,
    'json' => $body,
  ]
);
print_r($response->getBody()->getContents());

Ruby

require 'rest-client'
require 'json'

body = {
  "amount": 15_000,
  "bearer": 0,
  "callbackUrl": 'https://example.com/',
  "channels": %w[card bank],
  "currency": 'NGN',
  "customerFirstName": 'John',
  "customerLastName": 'Wick',
  "customerPhoneNumber": '2348032132100',
  "email": 'john.wick@credocentral.com',
  "metadata": {
    "bankAccount": '0114877128',
    "customFields": [
      { "variable_name": 'gender', "value": 'Male', "display_name": 'Gender' }
    ]
  }
  "//reference": "mTL022NzzQ0 - This must be Unique, if not present we will generate one",
  "//serviceCode": "201220045mG7mTL022zQ09 - If you have dynamic settlement service setup"
}
headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Public Key'
}

result =
  RestClient.post(
    'https://api.credocentral.com/transaction/initialize',
    body,
    headers: headers
  )

p JSON.parse(result)

Go

package main

import (
   "bytes"
   "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Public Key"},
    }
    var jsonData = []byte(`{
    "amount": 15000,
  "bearer": 0,
  "callbackUrl": "https://example.com/",
  "channels": ["card", "bank"],
  "currency": "NGN",
  "customerFirstName": "John",
  "customerLastName": "Wick",
  "customerPhoneNumber": "2348032132100",
  "email": "john.wick@credocentral.com",
  "metadata": {
    "bankAccount": "0114877128",
    "customFields": [
      {"variable_name": "gender", "value": "Male", "display_name": "Gender" }
    ]
  }
  "//reference": "mTL022NzzQ0 - This must be Unique, if not present we will generate one",
  "//serviceCode": "201220045mG7mTL022zQ09 - If you have dynamic settlement service setup"
}`);
    data := bytes.NewBuffer(jsonData)
    req, err := http.NewRequest("POST", "https://api.credocentral.com/transaction/initialize", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Python

import requests
body = {
   "amount": 15000,
    "bearer": 0,
    "callbackUrl": "https://example.com/",
    "channels": ["card", "bank"],
    "currency": "NGN",
    "customerFirstName": "John",
    "customerLastName": "Wick",
    "customerPhoneNumber": "2348032132100",
    "email": "john.wick@credocentral.com",
    "metadata": {
        "bankAccount": "0114877128",
        "customFields": [{"variable_name": "gender", "value": "Male", "display_name": "Gender"}]
    },
    "//reference": "mTL022NzzQ0 - This must be Unique, if not present we will generate one",
    "//serviceCode": "201220045mG7mTL022zQ09 - If you have dynamic settlement service setup"
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Public Key'
}

response = requests.post(
  'https://api.credocentral.com/transaction/initialize',
  headers = headers,
  body = body
)

print(response.json())

cURL

curl --request POST \
  --url https://api.credocentral.com/transaction/initialize \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Public Key' \
  --data '{
   "amount": 15000,
  "bearer": 0,
  "callbackUrl": "https://example.com/",
  "channels": ["card", "bank"],
  "currency": "NGN",
  "customerFirstName": "John",
  "customerLastName": "Wick",
  "customerPhoneNumber": "2348032132100",
  "email": "john.wick@credocentral.com",
  "metadata": {
    "bankAccount": "0114877128",
    "customFields": [
      {"variable_name": "gender", "value": "Male", "display_name": "Gender" }
    ]
  }
  "//reference": "mTL022NzzQ0 - This must be Unique, if not present we will generate one",
  "//serviceCode": "201220045mG7mTL022zQ09 - If you have dynamic settlement service setup"
}'

Response Parameters

Param	Description
status	Response status of the request
message	Response message describing the status of the request
data.authorizationUrl	This field holds a specialized link to process the initialized payment
data.reference	Unique case-sensitive transaction reference sent with the request or generated by Credo.
data.credoReference	Credo internal Unique case-sensitive transaction reference
execTime	Time it took to process this request
error	Validation error message if any

Example responses

200 (success)

{
  "status": 200,
  "message": "Successfully processed",
  "data": {
    "authorizationUrl": "https://www.credodemo.com/checkout/Sfhx00BA4801Zk1T47wf",
    "reference": "201220045mG7mTL022zQ09",
    "credoReference": "Sfhx00BA4801Zk1T47wf"
  },
  "execTime": 4.64879297,
  "error": []
}

400 (Bad request - Invalid input)

{
 "execTime": 4.64879297,
  "error": []
  "status": 400,
  "errorMessage": "Bad Request",
}

Redirect after successful payment

callbackUrl?status=0&errorMessage=Approved&transRef=Sfhx00BA4801Zk1T47wf&transAmou
nt=150.00&currency=NGN&reference=201220045mG7mTL022zQ09

Verify payment status

GET /transaction/{transRef}/verify

Use this endpoint to verify the status of a payment transaction. Calling this endpoint will return transaction details for the provided transRef for each transaction.

Path: /transaction/{transRef}/verify

Request Type: GET

Header: Authorization: api-secret-key

Content-Type: application/JSON

Request Headers

Param	Required	Description
api-secret-key	Yes	Your secret key. Use the test key for test mode and the live key for live mode
transRef	Yes	Transaction reference from the business or Credo.

Example requests

JavaScript

const headers = {
  Accept: 'application/json',
  Authorization: 'api-secret-key',
}

const url = 'https://api.credocentral.com/transaction/{transRef}/verify'
fetch(url, {
  method: 'GET',
  headers: headers,
})
  .then((res) => res.json())
  .then(console.log)

PHP

<?php

require 'vendor/autoload.php';

$headers = [
  'Accept' => 'application/json',
  'Authorization' => 'api-secret-key',
];

$client = new \GuzzleHttp\Client();

$response = $client->request(
  'GET',
  'https://api.credocentral.comtransaction/{transRef}/verify',
  [
    'headers' => $headers,
  ]
);
print_r($response->getBody()->getContents());

Ruby

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json', 'Authorization' => 'api-secret-key'
}

result =
  RestClient.get(
    'https://api.credocentral.com/transaction/{transRef}/verify',
    headers: headers
  )

p JSON.parse(result)

Go

package main

import (
   "bytes"
   "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"api-secret-key"},
    }

    req, err := http.NewRequest("GET", "https://api.credocentral.com/transaction/{transRef}/verify")
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Python

import requests

headers = {
  'Accept': 'application/json',
  'Authorization': 'api-secret-key'
}

response = requests.get(
  'https://api.credocentral.com/transaction/{transRef}/verify',
  headers = headers
)

print(response.json())

cURL

curl --request GET \
  --url https://api.credocentral.com/transaction/{transRef}/verify \
  --header 'Accept: application/json' \
  --header 'Authorization: api-secret-key'

Response Parameters

Param	Description
data.businessCode	Business unique identification number within our platform
data.businessRef	Unique case-sensitive transaction reference. Only alphanumeric characters are allowed. If you do not pass this parameter, Credo will generate a unique reference.
data.channelId	Credo’s internal channel ID
data.currencyCode	Currency charge should be performed. Allowed values are NGN or USD. It defaults to your integration currency.
data.customerId	Customer email during transaction initialization
data.debitedAmount	Total amount that was debited from the customer
data.metadata	Object containing any extra information you want to be recorded with the transaction. Fields within the custom_field object will appear on merchant receipts and within the transaction information on the Credo Dashboard.
data.serviceCode	Dynamic settlement service code
data.settlementAmount	Amount that will be settled to business
data.status	Transaction status - see page 3
data.transAmount	Requested/actual transaction amount
data.transFeeAmount	Transaction fee
data.transRef	Credo internal Unique case-sensitive transaction reference
data.transactionDate	Transaction processed date
error	Validation error message if any
execTime	Time it took to process this request
message	Response message describing the status of the request
status	Response status of the request

Example responses

200 (success)

{
  "status": 200,
  "message": "Successfully processed",
  "data": {
    "businessCode": "700607001390003",
    "transRef": "JunW00GkHm01vo0N96pk",
    "businessRef": "201220045mG7mTL022zQ09",
    "debitedAmount": 15325.0,
    "transAmount": 15000.0,
    "transFeeAmount": 325.0,
    "settlementAmount": 15000.0,
    "customerId": "john.wick@credocentral.com",
    "transactionDate": "2023-01-04 21:59:10",
    "channelId": 0,
    "currencyCode": "NGN",
    "status": 0,
    "metadata": [
      {
        "insightTag": "bankAccount",
        "insightTagValue": "0114877128"
      },
      {
        "insightTag": "gender",
        "insightTagValue": "Male",
        "insightTagDisplay": "Gender"
      }
    ]
  },
  "execTime": 0.0
}

400 (Bad request - Invalid input)

{
 "execTime": 4.64879297,
  "error": []
  "status": 400,
  "errorMessage": "Bad Request",
}