Examples

Example description file

This is an example of a description file.

{
  "openapi": "3.0.0",
  "info": { "title": "Payments API", "version": "1.0.0" },
  "paths": {
    "/openOrder": {
      "post": {
        "summary": "Open an order and mint a session token",
        "description": "Calls Nuvei openOrder.do with a checksum computed from the merchant secret key. The secret never leaves this process, which is why this call cannot live in the app.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "string",
                    "description": "Order amount, as a decimal string.",
                    "examples": ["10.00"]
                  },
                  "currency": {
                    "type": "string",
                    "description": "ISO 4217 currency code.",
                    "examples": ["EUR"]
                  },
                  "clientRequestId": {
                    "type": "string",
                    "description": "Optional; generated here when omitted."
                  },
                  "clientUniqueId": {"type": "string"},
                  "userTokenId": {"type": "string"},
                  "customData": {"type": "string"}
                },
                "required": ["amount", "currency"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The opened order. sessionToken is what the mobile SDK checks out with.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sessionToken": {
                      "type": ["string", "null"],
                      "description": "The session token the Nuvei mobile SDK requires. Null when the order could not be opened — read status/reason."
                    },
                    "merchantId": {"type": ["string", "null"]},
                    "merchantSiteId": {"type": ["string", "null"]},
                    "clientRequestId": {"type": ["string", "null"]},
                    "status": {
                      "type": ["string", "null"],
                      "description": "Nuvei request status, e.g. SUCCESS or ERROR."
                    },
                    "errCode": {"type": ["integer", "string", "null"]},
                    "reason": {"type": ["string", "null"]},
                    "googlePay": {
                      "type": ["object", "null"],
                      "description": "Non-secret Google Pay ids, or null when Google Pay is not configured.",
                      "properties": {
                        "merchantId": {"type": ["string", "null"]},
                        "merchantName": {"type": ["string", "null"]},
                        "gateway": {"type": ["string", "null"]},
                        "gatewayMerchantId": {"type": ["string", "null"]}
                      }
                    },
                    "applePay": {
                      "type": ["object", "null"],
                      "description": "Non-secret Apple Pay ids, or null when Apple Pay is not configured.",
                      "properties": {
                        "merchantId": {"type": ["string", "null"]},
                        "merchantName": {"type": ["string", "null"]}
                      }
                    }
                  },
                  "required": ["sessionToken"]
                }
              }
            }
          }
        }
      }
    }
  }
}

Three things make this file usable:

• The version key. "openapi" (or "swagger" for older documents) is how the builder tells a real description from any other JSON file.
• The path. /openOrder here. The name does not have to match exactly - the builder also recognizes open_order, open-order, openSession, paymentSession, and similar spellings. It must be a post.
• The response. The 200 response must include a sessionToken field. This is the value the mobile SDK checks out with, so an endpoint that omits it cannot drive a payment, however correct its name looks.

Everything else is optional. Your real description will list many more endpoints and far more detail - that is expected, and the builder ignores the parts it does not need.