Payment (Payin)

Purpose

The POST /v1/payin/sessions endpoint allows a merchant to create a secure payment session between their system and the payment platform. This session corresponds to a payment intent: it does not charge the customer until they confirm or validate the transaction.

Request Details

Request Parameters

Request Example

{
  "reference": "{{$randomUUID}}",
  "accountId": "merchant_9923lkdz",
  "amount": 300,
  "msisdn": "+2250702968786",
  "customerName": "John Doe",
  "country": "CI"
}

Response Example

{
  "type": "payin",
  "fee": 6,
  "reference": "tr_fhchi842jyimwiugjgszcxvb8n",
  "phoneNumber": "+2250700000000",
  "amount": 300,
  "chargedAmount": 306,
  "status": "processing",
  "currency": "XOF",
  "customerReference": "ef76fb64-af0b-4c37-8729-bf61d85721fd",
  "confirmationRequired": true,
  "confirmationStatus": "none",
  "paymentUrl": "https://link.novasend.app/link/{shortCode}",
  "createdAt": "2025-08-22T01:34:48.189Z"
}

Response Interpretation

The confirmationRequired and confirmationStatus Attributes

confirmationRequired

• Type: boolean
• Possible values:
  • true → the customer must confirm the payment (e.g., OTP entry, approval in their mobile wallet, or click on a secure link).
  • false → the payment is automatically validated (case of internal transfers or instant payments).
• Role: Allows the merchant to know if they must wait for a customer action before considering the payment complete.

  Example:

  • If confirmationRequired = true, the system sends a validation link (paymentUrl) to the customer.
  • The payment then goes to "processing" status until the customer responds.

confirmationStatus

• Type: string

• Possible values:

  Value	Description
  none	No response from the customer (initial status).
  accepted	The customer confirmed the payment (OTP validated, or clicked "Accept").
  declined	The customer explicitly refused the payment.
  expired	Confirmation deadline exceeded (timeout).

• Role: Provides the current state of the customer validation process. This status evolves dynamically based on customer actions and can be tracked via:

  • Webhook (payin.confirmed, payin.declined)
  • Or via a GET /v1/payin/{reference} request.

Obligation

• Always store reference and customerReference to track the transaction.
• Display the paymentUrl link to the customer for validation if confirmationRequired = true.
• If confirmationStatus = declined or expired, the payment should be considered invalid.

Payment Status

Purpose

This endpoint allows you to check the status of a payment initiated via the Merchant API at any time.

It is particularly useful for:

• Verifying customer confirmation (accepted or declined).
• Getting the final payment status (success, failure, pending).
• Accessing enriched information about the transaction processed by the Core System (in the transaction field).

Request Details

How It Works

When a merchant initiates a payment (POST /v1/payin/sessions), the API returns an initial status of processing or processed.

The payment then goes through several internal stages:

This endpoint allows you to check the complete progress of a payment from its reference.

Response Example

{
  "type": "payin",
  "fee": 6,
  "reference": "mtr_fhscgaywizujwjyymlge1hncaq",
  "phoneNumber": "+2250700000000",
  "customerName": "John Doe",
  "amount": 300,
  "chargedAmount": 306,
  "status": "processed",
  "currency": "XOF",
  "customerReference": "55a4e677-5700-4ed0-9a2a-9300db894ddb",
  "confirmationRequired": true,
  "confirmationStatus": "none",
  "createdAt": "2025-08-22T02:00:16.026Z",
  "transaction": {
    "reference": "tr_dkjd5ljficphlqmt",
    "status": "completed",
    "customerName": "dd soûl",
    "processedAt": "2025-11-05T16:12:42.096Z",
    "phoneNumber": "+2250700000000",
    "amount": "153.00",
    "fees": "0.00",
    "chargedAmount": "153.00",
    "currency": "XOF"
  },
  "failure": null
}

Response Interpretation

transaction Key

The transaction field represents the final transaction recorded in the Core System once the payment is validated or rejected.

Reading Example

• If status = "processed" and transaction.status = "completed" → ✅ Payment successful and confirmed.
• If status = "processed" but transaction.status = "failed" → ⚠️ Payment recorded but refused by customer.
• If transaction is null or {} in this case, the payment has not yet been confirmed by the customer.
• If failure contains an object → error information will be present (code, message, etc.).

Obligation

• Always store the reference and customerReference for correlation.
• The transaction.status field is the final source of truth on the settlement system side.