Skip to main content

Create Payment

POST {BASE_URL}/payment

Initialises a payment. This method receives input parameters as a JSON body.

Parameters​

  • amount (required): Payment amount in cents.
  • currency (required): Payment currency code.
  • psp (required): Payment service provider name. For testing purposes demo can be used.
  • callbackUrl (required): This URL will be called with POST method and payment status as JSON body.
  • redirectSuccessUrl (optional): User will be redirected to this URL in case of successful payment.
  • redirectFailureUrl (optional): User will be redirected to this URL in case of failed payment.
  • orderId (required): Unique order identifier.
  • customer (required): Customer data object
    • id (optional): Customer identification
    • email (required): Customer email
    • country (optional): Customer country
    • state (optional): Customer state
    • city (optional): Customer city
    • region (optional): Customer region
    • address (optional): Customer address
    • street (optional): Customer street
    • postcode (optional): Customer postcode
    • phone (optional): Customer phone
    • ip (optional): Customer IP address
    • firstName (optional): Customer first name
    • lastName (optional): Customer last name

Response​

Returns a JSON object with the following properties:

  • redirectUrl Customer needs to be redirected to this URL in order to proceed with the transaction
  • payment Payment result object
    • id The unique identifier of the transaction
    • amount Payment amount object
      • amount Amount in cents
      • currency Currency code
    • status Payment status
    • createdAt Payment created at timestamp

Example​

Request:

fetch('https://sandbox-api.ninjapay.tech/api/v1/payment', {
  method: 'post',
  headers: {
    Authorization: 'Bearer MERCHANT_SECRET_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 10000,
    currency: "EUR",
    psp: "demo",
    callbackUrl: "https://example.org/callback",
    redirectSuccessUrl: "https://example.org/success",
    redirectFailureUrl: "https://example.org/fail",
    orderId: "order_1234",
    customer: {
      id: "customer_1234",
      email: "mail@mail.org",
      country: "NL",
      city: "City",
      region: "Some Region",
      address: "Some Str 1",
      postcode: "XXAA11",
      phone: "0123123123",
      ip: "127.0.0.1",
      firstName: "John",
      lastName: "Snow",
      street: "Str",
      state: "NA"
    },
  }),
});

Response:

{
  "payment": {
    "id": "cb27456c-d6ee-4de9-b6eb-9970c485aa64",
    "amount": {
      "amount": "10000",
      "currency": "EUR"
    },
    "receivedAmount": {
      "amount": "0",
      "currency": "EUR"
    },
    "status": "new",
    "createdAt": "2024-02-28T17:27:32+00:00"
  },
  "redirectUrl": "https://example.org"
}

Errors​

This API uses the following error codes:

  • 400 Bad Request The request was malformed or missing required parameters
  • 401 Unauthorized The API key provided was invalid or missing
  • 404 Not Found The requested resource was not found
  • 500 Internal Server Error An unexpected error occurred on the server