Create Charge

Create a new charge on a customer's debit card

POST {{ BASE_URL }}/v1/corporate/charge

Body Parameters

Property	Data Type	Description	Example	Required
amount	number	The amount to charge	200	Yes
currency	string	The currency of the payment. This can be NGN or USD	"NGN"	Yes
reference	string	Your unique reference for the transaction	"23456789876CBD"	No
redirectUrl	string	Url you want to redirect to after successful or failed payment	"https://...."	NO
description	string	Description of the transaction	"Payment for card"	No
deviceIp	string	IP address of the customer's device or your device	"192.168.206.32"	Yes
card	object	The card object that holds card details	{...}	Yes
card.number	string	Debit card number	"539983446085..."	Yes
card.expiryMonth	string	Debit card expiry month	"03"	Yes
card.expiryYear	string	Debit card expiry year	"26"	Yes
card.cvv	string	Debit card security number ( CVV )	"111"	Yes
card.name	string	Debit card holder name	"Terraswitch Limited"	Yes
customer	object	The customer object that holds customer details	{...}
customer.firstName	string	Customer first name	"John"
customer.lastName	string	Customer last name	"Doe"
customer.phoneNumber	string	Customer phone number without country code	"08137031202"
customer.phoneCode	string	Country code for customer's phone number.	"+234"
metadata	Array of objects	Additional parameters you want using the metadata object. Learn how to craft metadata here	[ {...}, {...} ]	No

Node.js

import Axios from 'axios';

// set the api url
const API_URL = `${BASE_URL}/v1/corporate/charge`;

// define request body
const data = {
    amount: 20,
    reference: "",
    redirectUrl: "https://staging-app.terraswitching.com/verify",
    description: "Staff payment for internal training",
    deviceIp: "",
    card: {
      number: "4007589999999961",
      expiryMonth: "06",
      expiryYear: "27",
      cvv: "111",
      name: "Terraswitch Limited"
    },
    customer: {
      firstName: "Oluwatobi",
      lastName: "Immanuel",
      email: "[email protected]",
      phoneNumber: "08137031202",
      phoneCode: "+234"
    },
    metadata: [
      {
        staffId: "002RTOPG",
        department: "engineering"
      }
    ]
}

// make request using axios
Axios({
    method: "POST",
    url: `${API_URL}`,
    headers: {
        lg: 'en',
        ch: 'web'
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
    },
    data: data
}).then((resp) => {
    console.log(resp)
}).catch((err) => {
    console.log(err)
})

Response . PIN Required

{
  error: false,
  errors: [],
  data: {
    nextStep: "card PIN is required",
    displayText: "enter card pin",
    status: "pending",
    reference: "TSXA96227AAAB93491B",
    type: "pin",
    path: "send_pin",
    url: "",
    statusCode: 206,
    metadata: {
      reference: "TSXA96227AAAB93491B",
      type: "send_pin"
    }
  },
  message: "enter card pin",
  status: 206
}

Response . Redirect

{
  error: false,
  errors: [],
  data: {
    nextStep: "redirect customer to the url provided",
    displayText: "redirect customer to the url provided",
    status: "pending",
    reference: "TSX1152FCEECC0F474E",
    type: "url",
    url: "https://dev-bcp.blusalt.net/cb/auth/BFS56196e8c9f8b4f7CCa17FEE7F09bDb",
    statusCode: 206,
    metadata: {
      transactionRef: "TRN-J7KJHHC8A2DIFHK2GCI13KC78I34FE3B",
      status: "PENDING_AUTH"
    }
  },
  message: "",
  status: 206
}

After creating a charge, you will be most likely required to authorize the charge. For this, you need to call the authorize-charge endpoint based on the response above.

Charge authorization types

For each charge created, you will be required to authorize the charge depending on the type ( i.e. brand ) of the card you are using. Below are the authorization types based on debit card brands.

Brand	PIN	OTP	3DS	Action
Verve	Yes	Yes	No	Call authorize-charge endpoint
Mastercard	No	No	Yes	Redirect customer to url provided
VISA	No	No	Yes	Redirect customer to url provided