Skip to main content
API docs by Redocly

Nopan API (v1)

Download OpenAPI specification:Download

Download Nopan Postman collection: Download

Authentication APIs

This section covers the endpoints required for securely obtaining OAuth 2.0 access tokens to interact with the Nopan API. These APIs support machine-to-machine (M2M) authentication using mutual TLS (mTLS) and client credentials. A valid access token is required to authorize all subsequent requests to protected resources.

Get access token

Get an access token via OAuth2

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "client_credentials"

OAuth2 grant type. Must be set to client_credentials to indicate machine-to-machine authentication using client credentials.
Example: client_credentials

processing_account_id
required
string

Unique organization account ID issued to the client during onboarding. Used to identify the merchant or integration making the request.
Example: merchant-abc123

scope
string

Optional space-delimited list of scopes the client is requesting access to. Used to limit the access token's permissions. Default is payments:read
Example: payments:read payments:process

Responses

Request samples

Content type
application/x-www-form-urlencoded

Get access token via OAuth2 by submitting form

grant_type=client_credentials&processing_account_id=your-organization-id&scope=payments:process

Response samples

Content type
application/json

Access token itself, how long it is valid for in seconds and other information

{
  • "access_token": "header.payload.signature",
  • "expires_in": 7200,
  • "refresh_expires_in": 0,
  • "token_type": "Bearer",
  • "not-before-policy": 0,
  • "scope": "payments:read"
}

Payment Processing APIs

This section provides a set of operations for initiating and managing payments through the Nopan API. These endpoints enable clients to request payments, handle SCA, and track the status of transactions in real time. Designed for seamless integration, the APIs support secure and compliant payment workflows for a variety of use cases including e-commerce, invoicing, and in-app purchases.

Initiate payment

Starts a new payment flow. The client provides payment details, and the response includes a redirect URL for the payer's SCA.

Request Body schema: application/json
required
processingAccountId
required
string non-empty

The organization account ID provided at onboarding
Example: merchant-1234

clientTransactionId
required
string non-empty

The unique client's internal transaction ID
Example: order11234

returnUrl
required
string non-empty

The client's redirect destination after SCA completion
Example: https://api.merchant.com/callback?ref=order1234

transactionType
required
string
Enum: "ONE_TIME" "RECURRING" "TOKENIZED"

Requesting transaction type
• ONE_TIME One time payment without storing payment information (COF)
• RECURRING For recurring payments. Requires mandate details.
• TOKENIZED Securely stores payment information (COF). Auto capture is not allowed.

required
object

Monetary details of the transaction

required
object

Payment scheme provider details

required
object

Payer identity information

object

Information about where the transaction was requested

object

Free map of tags set by the client
Example

{
  "key": "value",
  "experiment": "checkout_A",
  "promo_code": "SPRING2025"
}

Responses

Request samples

Content type
application/json
Example

Initiates a Blik payment request

{
  • "processingAccountId": "merchant",
  • "clientTransactionId": "order123",
  • "returnUrl": "https://api.merchant.callback?ref=order123",
  • "transactionType": "ONE_TIME",
  • "paymentDetails": {
    },
  • "providerDetails": {
    },
  • "payerDetails": {
    },
  • "requestContext": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json

The request has been accepted and awaits for SCA

{
  • "transactionId": "ee2anef9bt",
  • "clientTransactionId": "order123",
  • "returnUrl": "https://api.merchant.callback?ref=order123",
  • "providerDetails": {
    },
  • "status": "PENDING",
  • "step": "INITIATE",
  • "statusInfo": {
    }
}

Finalize payment

Finalizes a two-step payment, optionally capturing funds if configured. For one-step payments, it serves as the merchant's acknowledgement.

Request Body schema: application/json
required
processingAccountId
required
string non-empty

The organization account ID provided at onboarding
Example: merchant-1234

transactionId
required
string non-empty

Nopan's transaction ID
Example: ee2anef9bt

Responses

Request samples

Content type
application/json

Finalizes a payment

{
  • "processingAccountId": "merchant",
  • "transactionId": "ee2anef9bt"
}

Response samples

Content type
application/json
Example

The payment has been approved and ready for capture

{
  • "transactionId": "ee2anef9bt",
  • "clientTransactionId": "order123",
  • "paymentDetails": {
    },
  • "status": "APPROVED",
  • "step": "FINALIZE",
  • "statusInfo": {
    }
}

Charge payment

Triggers a recurring or token-based payment without user interaction in one step.

Request Body schema: application/json
required
processingAccountId
required
string non-empty

The organization account ID provided at onboarding
Example: merchant-1234

clientTransactionId
required
string non-empty

The unique client's internal transaction ID
Example: order11234

required
object

Monetary details of the transaction

required
object

Payment scheme provider details

required
object

Payer identity information

object

Information about where the transaction was requested

object

Free map of tags set by the client
Example

{
  "key": "value",
  "experiment": "checkout_A",
  "promo_code": "SPRING2025"
}

Responses

Request samples

Content type
application/json
{
  • "processingAccountId": "string",
  • "clientTransactionId": "string",
  • "paymentDetails": {
    },
  • "providerDetails": {
    },
  • "payerDetails": {
    },
  • "requestContext": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "processingAccountId": "string",
  • "transactionId": "string",
  • "clientTransactionId": "string",
  • "providerDetails": {
    },
  • "metadata": {
    },
  • "step": "INITIATE",
  • "status": "ACCEPTED",
  • "statusInfo": {
    }
}

Capture payment

Captures funds from a previously finalized payment without auto capture. Enables delayed capture scenarios for clients who prefer control over timing

Request Body schema: application/json
required
processingAccountId
required
string non-empty

The organization account ID provided at onboarding
Example: merchant-1234

clientTransactionId
required
string non-empty

The unique client's internal transaction ID
Example: order11234

transactionId
required
string non-empty

Nopan's transaction ID
Example: ee2anef9bt

required
object

Monetary details of the transaction

Responses

Request samples

Content type
application/json

Captures partial or full amount

{
  • "processingAccountId": "merchant",
  • "clientTransactionId": "order-1234",
  • "transactionId": "ee2anef9bt",
  • "paymentDetails": {
    }
}

Response samples

Content type
application/json

The amount has been captured

{
  • "transactionId": "ee2anef9bt",
  • "clientTransactionId": "order123",
  • "paymentDetails": {
    },
  • "status": "APPROVED",
  • "step": "CAPTURE",
  • "statusInfo": {
    }
}

Cancel payment

Cancels an initiated but not yet captured payment. Prevents future fund movements.

Request Body schema: application/json
required
processingAccountId
required
string non-empty

The organization account ID provided at onboarding
Example: merchant-1234

clientTransactionId
required
string non-empty

The unique client's internal transaction ID
Example: order11234

transactionId
required
string non-empty

Nopan's transaction ID
Example: ee2anef9bt

Responses

Request samples

Content type
application/json

Cancels a payment

{
  • "processingAccountId": "merchant",
  • "clientTransactionId": "order-1234",
  • "transactionId": "ee2anef9bt"
}

Response samples

Content type
application/json
Example

Payment initiated and canceled

{
  • "transactionId": "ee2anef9bt",
  • "clientTransactionId": "order-1234",
  • "providerDetails": {},
  • "payerDetails": {
    },
  • "paymentDetails": {
    },
  • "metadata": {
    },
  • "status": "CANCELED",
  • "step": "FINALIZE",
  • "statusInfo": {
    }
}

Refund payment

Refunds a previously captured payment, either fully or partially. Used to reverse a transaction after funds have already been settled.

Request Body schema: application/json
required
processingAccountId
required
string non-empty

The organization account ID provided at onboarding
Example: merchant-1234

clientTransactionId
required
string non-empty

The unique client's internal transaction ID
Example: order11234

transactionId
required
string non-empty

Nopan's transaction ID
Example: ee2anef9bt

required
object

Monetary details of the transaction

Responses

Request samples

Content type
application/json
{
  • "processingAccountId": "string",
  • "clientTransactionId": "string",
  • "transactionId": "string",
  • "paymentDetails": {
    }
}

Response samples

Content type
application/json
{
  • "transactionId": "string",
  • "processingAccountId": "string",
  • "clientTransactionId": "string",
  • "providerDetails": {
    },
  • "payerDetails": {
    },
  • "paymentDetails": {
    },
  • "metadata": {
    },
  • "step": "INITIATE",
  • "status": "ACCEPTED",
  • "statusInfo": {
    }
}

Payment status

Returns the current status of a payment. Optionally includes recent history.

path Parameters
transactionId
required
string

Responses

Response samples

Content type
application/json
{
  • "transactionId": "string",
  • "processingAccountId": "string",
  • "clientTransactionId": "string",
  • "providerDetails": {
    },
  • "payerDetails": {
    },
  • "paymentDetails": {
    },
  • "metadata": {
    },
  • "step": "INITIATE",
  • "status": "ACCEPTED",
  • "statusInfo": {
    }
}

Testing APIs

The Nopan API includes a sandbox environment and test endpoints to help developers safely simulate, mock and validate payment flows without processing real transactions. These testing APIs mirror the behavior of the live endpoints, allowing you to initiate payments, trigger SCA flows, and verify callbacks using predefined test data. This environment is ideal for integration testing, QA workflows, and development staging before going live.

Mock payment flow

Mocks a payment flow. Mock will match requests using processingAccountId and key.

Request Body schema: application/json
required
processingAccountId
required
string non-empty

The organization account ID provided at onboarding
Example: merchant-1234

required
object

Information about the key type and value to be mocked

type
required
string
Enum: "MOCK" "PASSTHROUGH"

The mock type
• MOCK Use Mock engine
• PASSTHROUGH Use real payment scheme provider

oneTime
boolean

If true, the mock will be deleted for that step after one call

object

Information to be mocked for each of the payment steps

Responses

Request samples

Content type
application/json
Example

Create a mock for all the steps in MOCK mode.

{
  • "processingAccountId": "merchant",
  • "key": {
    },
  • "type": "MOCK",
  • "oneTime": false,
  • "steps": {
    }
}

Response samples

Content type
application/json
Example

The JSON is not properly formatted

{
  • "status": "DECLINED",
  • "statusInfo": {
    },
  • "callId": "a3c8cdef0a134df4-2e31b1"
}

Webhooks

API of the webhooks notifications Nopan will send if configured in the portal.

Payment initiated notification

Notifies you when a payment has been initiated. The exact path of the request is configured through our portal.

Request Body schema: application/json
required
notificationId
string <uuid>

Unique id of the notification.
Example: 56562de8-9b89-4628-b2fe-cd1b2cc1e95b

transactionId
string

Nopan's transaction ID
Example: ee2anef9bt

clientTransactionId
string

The unique client's internal transaction ID
Example: order11234

notificationType
string
Enum: "PAYMENT_INITIATED" "PAYMENT_FINALIZED" "PAYMENT_CAPTURED"

Responses

Request samples

Content type
application/json

A Payment has been initiated

{
  • "notificationId": "2d591c23-85b1-4e8c-a6bd-74d89f8955c5",
  • "transactionId": "ee2anef9bt",
  • "notificationType": "PAYMENT_FINALIZED"
}

Payment finalized notification

Notifies you when a payment has been finalized. The exact path of the request is configured through our portal.

Request Body schema: application/json
required
notificationId
string <uuid>

Unique id of the notification.
Example: 56562de8-9b89-4628-b2fe-cd1b2cc1e95b

transactionId
string

Nopan's transaction ID
Example: ee2anef9bt

clientTransactionId
string

The unique client's internal transaction ID
Example: order11234

notificationType
string
Enum: "PAYMENT_INITIATED" "PAYMENT_FINALIZED" "PAYMENT_CAPTURED"

Responses

Request samples

Content type
application/json

The amount has been captured

{
  • "notificationId": "2d591c23-85b1-4e8c-a6bd-74d89f8955c5",
  • "transactionId": "ee2anef9bt",
  • "notificationType": "PAYMENT_FINALIZED"
}

Payment captured notification

Notifies you when a payment has been captured. The exact path of the request is configured through our portal.

Request Body schema: application/json
required
notificationId
string <uuid>

Unique id of the notification.
Example: 56562de8-9b89-4628-b2fe-cd1b2cc1e95b

transactionId
string

Nopan's transaction ID
Example: ee2anef9bt

clientTransactionId
string

The unique client's internal transaction ID
Example: order11234

notificationType
string
Enum: "PAYMENT_INITIATED" "PAYMENT_FINALIZED" "PAYMENT_CAPTURED"

Responses

Request samples

Content type
application/json

The amount has been captured

{
  • "notificationId": "2d591c23-85b1-4e8c-a6bd-74d89f8955c5",
  • "transactionId": "ee2anef9bt",
  • "notificationType": "PAYMENT_CAPTURED"
}