NAV Navbar
shell
  • Overview
  • API Overview
  • QR Codes
  • Payments
  • Cash Ups
  • Overview

    API Base URL

    https://pos.snapscan.io/merchant/api/v1

    The SnapScan API is REST-like and relies on HTTP status codes to indicate API errors. We support CORS so that you can interact with our API through a client-side web application. We return JSON in all responses from the API.

    We currently have both Magento and WooCommerce plugins available. Please contact help@snapscan.co.za for more information.

    API Overview

    Authentication

    # Authentication through HTTP Basic Auth
    curl -u your-api-key: "api_endpoint_here"
    

    The following response can be expected for unauthorised requests:

    HTTP/1.1 401 UNAUTHORIZED
    Content-Type: application/json
    
    {
      "message": "Unauthorised"
    }
    

    Access to the API is protected through an API key. Authentication occurs via HTTP Basic Auth. The basic auth username must be set to your API key and the password should be left blank.

    All requests must be made over HTTPS and authenticated. Any request over HTTP will fail.

    Error Codes

    Example of an error response when an invalid parameter is provided:

    HTTP/1.1 400 BAD REQUEST
    Content-Type: application/json
    
    {
      "message": "startDate is not valid"
    }
    

    HTTP status codes are use to indicate the success or failure of an API request. In general 2xx indicates success, 4xx indicates failure due to information provided by you (eg. a required parameter is missing) while 5xx indicates that the failure was caused by the SnapScan servers (or we were unable to service the request at this time). A valid error response from us will always be a JSON object containing a message key.

    Pagination

    All API resources that can return multiple records (eg. the payments API) are paginated. These endpoints provide the same set of parameters that allow you to specify which page and how many records per page to return.

    Query Parameters

    Parameter Default Description
    page 1 The current page.
    perPage 50 The number of records to return per page (maximum: 100).
    offset 0 The offset to start from.

    Response Headers

    The following pagination headers are included in the response. All pagination headers are integers.

    Header Description
    X-Total The total number of records in the query.
    X-Total-Pages The number of pages that the query is made up of.
    X-Page The current page.
    X-Per-Page The number of records per page.
    X-Next-Page The next page.
    X-Prev-Page The prev page
    X-Offset The offset being used.

    Webhook

    We recommend that you make use of a webhook to be notified of payment completion due to the real-time nature of the system. During your account set up we can configure a URL to which we will POST payment objects as we determine their status. We will only notify you of completed and errored payments through the webhook.

    Note that webhooks should be treated as an unauthenticated event stream. If payment spoofing is a concern and you require higher levels of certainty about a payment, make an authenticated API call to our get payment (or get all payments) endpoint.

    We POST the data as an application/x-www-form-urlencoded JSON string under the payload key.

    QR Codes

    Creating the URL

    All SnapScan QR codes contain a SnapCode to identify the merchant. Additional parameters amount and id can be included to pre-populate the amount owed and a unique order number on the customers phone. These values will be associated with the payment as requiredAmount and merchantReference in the API.

    Standard SnapCode

    Your unique SnapCode will be displayed on your QR code stand or may be supplied by customer support. Let's say yours is "shopalot", your URL would look as follows:

    Payment Detail URL
    Merchant: Shopalot
    SnapCode: shopalot
    https://pos.snapscan.io/qr/shopalot

    Adding payment parameters

    Used for online checkout, point-of-sale, vending machines and more.

    In some cases, it is useful for the merchant to include the amount owed and a unique reference number to reconcile payments.

    If a merchant wishes to embed the amount and reference of a payment so that this information is pulled through into the users app at payment - they simply add query parameters to the payment URL. For example:

    Payment Detail URL
    Merchant: Shopalot
    SnapCode: shopalot
    ID: Ord123
    Amount: R10.00
    https://pos.snapscan.io/qr/shopalot?id=Ord123&amount=1000

    Limiting successful payments to unique Id

    To prevent the customer from successfully paying the same reference twice, and from paying less than the specified &amount= parameter, simply add &strict=true to the end of a payment URL.

    Payment Detail URL
    Merchant: Shopalot
    SnapCode: shopalot
    ID: Ord123
    Amount: R10.00
    Strict: true
    https://pos.snapscan.io/qr/shopalot?id=Ord123&amount=1000&strict=true

    Adding extra parameters

    You can add extra parameters to the payment URL. These details will be passed back under the extra attribute in payments.

    https://pos.snapscan.io/qr/shopalot?customValue=123

    Generating a QR code

    Use the QR code generator API to display a code on your site. This allows for the specification of the image type as well as the size. See the code snippet to the right as an example.

    An example QR code in HTML:

    <a href="https://pos.snapscan.io/qr/shopalot?id=Ord123&amount=1000">
      <img src="https://pos.snapscan.io/qr/shopalot.svg?id=Ord123&amount=1000&snap_code_size=125">
    </a>
    

    external link

    Payments

    The API's main purpose is to provide you with various ways to query the status of payments that were made against your merchant account.

    Credit card processing can take a few seconds and because the API caters for real-time queries it affects how the API works. If a query contains any pending payments it is necessary to poll the API until the result is available, for real-time applications we recommend that you make use of our webhook service. Seeing as webhooks can fail due to various reasons (eg. timeouts) an integration should allow the client to manually request the status of payments.

    The payment object

    An example of a payment object:

    {
      "id": 1,
      "status": "completed",
      "date": "1999-12-31T23:00:00Z",
      "totalAmount": 1000,
      "tipAmount": 0,
      "requiredAmount": 1000,
      "snapCode": "STB115",
      "snapCodeReference": "Till Point #1",
      "userReference": "John Doe",
      "merchantReference": "INV001",
      "statementReference": "SNAPSCAN 20150109",
      "authCode": "123456",
      "extra": {
        "customValue": "123"
      },
      "deliveryAddress": {
        "address1": "13 Long Street",
        "address2": "CBD",
        "town": "Cape Town",
        "postalCode": "8001",
        "country": "South Africa"
      }
    }
    

    Payment objects always have all possible attributes but if an attribute is not defined it will be null.

    The following attributes are provided by all QR codes:

    Attribute Type Description
    id Integer Our unique ID for the payment. The ID is sequential and starts from 1.
    status String Indicates whether the payment was successful or failed. Possible values are: completed, error, pending
    date String The UTC date of when the payment was started. The date is ISO8601 formatted, eg: 1999-12-31T23:00:00Z
    totalAmount Integer The total amount in cents paid by the user.
    tipAmount Integer If this feature is enabled for your account it will include the tip amount in cents paid by the user (totalAmount includes the tipAmount).
    snapCode String The unique reference encoded in the QR code which is linked to your account. The code is always the same for payments made through the QR.
    snapCodeReference String A reference that you can choose to be defined on the QR code which will always be the same for payments made through it.
    userReference String If this feature is enabled for your account it will include the reference defined by the user when he made the payment.
    statementReference String If the payment has been settled into your bank account it will include the statement reference for the associated settlement. This is the reference that will appear on your bank statement.
    extra Object Any extra parameters that were sent as part of the payment URL.
    deliveryAddress Address If delivery is enabled for your account it will include the delivery address entered by the user.

    Address has the following attributes:

    Attribute Type Description
    address1 String The first address line entered by the user.
    address2 String The second address line entered by the user.
    town String The town entered by the user.
    postalCode String The postal code entered by the user.
    country String The country entered by the user.

    If you are generating QR codes for payments various extra attributes can be encoded in the QR:

    Attribute Type Description
    requiredAmount Integer The amount in cents that was required to be paid by the user.
    merchantReference String A unique reference defined by you and encoded in the QR code.
    authCode String A random number that is generated by us for payments that have a required amount and merchant reference defined. The number is 6 digits long and will be displayed to the user if the payment was successful.

    Get all payments

    curl -u your-api-key: "https://pos.snapscan.io/merchant/api/v1/payments"
    

    The above command returns JSON structured like this:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
      {
        "id": 2,
        "status": "error",
        "date": "2000-01-01T01:00:00Z",
        "totalAmount": 2050,
        "tipAmount": 550,
        "requiredAmount": 1500,
        "snapCode": "STB115",
        "snapCodeReference": "Till Point #1",
        "userReference": "Jane Doe",
        "merchantReference": "INV002",
        "statementReference": "SNAPSCAN 20150109",
        "authCode": "654321",
        "extra": null,
        "deliveryAddress": null
      },
      {
        "id": 1,
        "status": "completed",
        "date": "1999-12-31T23:00:00Z",
        "totalAmount": 1000,
        "tipAmount": 0,
        "requiredAmount": 1000,
        "snapCode": "STB115",
        "snapCodeReference": "Till Point #1",
        "userReference": "John Doe",
        "merchantReference": "INV001",
        "statementReference": "SNAPSCAN 20150109",
        "authCode": "123456",
        "extra": null,
        "deliveryAddress": null
      }
    ]
    

    Returns all payments that have been made against your QR codes (SnapCodes). If no parameters are provided all payments made to you will be returned. By default if the status parameter isn't provided completed, errored and pending payments will be returned.

    A successful response is always an array and is paginated. If no payments match your query parameters the array will be empty. Payments are ordered by descending IDs, ie. the first payment will always be the latest in the returned result.

    HTTP Request

    GET https://pos.snapscan.io/merchant/api/v1/payments

    Query Parameters

    All parameters are optional.

    Parameter Description
    startDate Payments that were started at or after this time, eg: 2000-01-01T01:00:00Z
    endDate Payments that were started before this time, eg: 2000-01-01T01:00:00Z
    status A comma separated string of the following values: completed, error or pending, eg. completed,pending
    snapCode Payments with the SnapCode.
    snapCodeReference Payments with the SnapCode reference.
    userReference Payments with the user reference.
    merchantReference Payments with your reference.
    statementReference Payments included in the settlement with the provided reference.

    Response Codes

    Description HTTP Status JSON Response
    OK 200 Array of payment objects
    Invalid parameter 400 Object containing a message key

    Get a payment

    curl -u your-api-key: "https://pos.snapscan.io/merchant/api/v1/payments/1"
    

    The above command returns JSON structured like this:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "id": 1,
      "status": "completed",
      "date": "1999-12-31T23:00:00Z",
      "totalAmount": 1000,
      "tipAmount": 0,
      "requiredAmount": 1000,
      "snapCode": "STB115",
      "snapCodeReference": "Till Point #1",
      "userReference": "John Doe",
      "merchantReference": "INV001",
      "statementReference": "SNAPSCAN 20150109",
      "authCode": "123456",
      "extra": null,
      "deliveryAddress": null
    }
    

    Returns a single payment.

    HTTP Request

    GET https://pos.snapscan.io/merchant/api/v1/payments/{id}

    Route Parameters

    The id route parameter is required.

    Parameter Description
    id The sequential ID of the payment.

    Response Codes

    Description HTTP Status JSON Response
    OK 200 A payment object
    ID doesn't exist 404 Object containing a message key

    Get all cash up payments

    curl -u your-api-key: "https://pos.snapscan.io/merchant/api/v1/payments/cash_ups/1e07ac748d2627ba"
    

    The above command returns JSON structured like this:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
      {
        "id": 3,
        "status": "completed",
        "date": "2000-01-01T01:00:00Z",
        "totalAmount": 2050,
        "tipAmount": 550,
        "requiredAmount": 1500,
        "snapCode": "STB115",
        "snapCodeReference": "Till Point #1",
        "userReference": "Jane Doe",
        "merchantReference": "INV002",
        "statementReference": "SNAPSCAN 20150109",
        "authCode": "654321",
        "extra": null,
        "deliveryAddress": null
      },
      {
        "id": 1,
        "status": "completed",
        "date": "1999-12-31T23:00:00Z",
        "totalAmount": 1000,
        "tipAmount": 0,
        "requiredAmount": 1000,
        "snapCode": "STB115",
        "snapCodeReference": "Till Point #1",
        "userReference": "John Doe",
        "merchantReference": "INV001",
        "statementReference": "SNAPSCAN 20150109",
        "authCode": "123456",
        "extra": null,
        "deliveryAddress": null
      }
    ]
    

    If the period contains any pending payments you can expect the following response:

    HTTP/1.1 500 INTERNAL SERVER ERRROR
    Content-Type: application/json
    
    {
      "message": "The query is not ready yet because the specified cash up period contains pending payments, please try again in a moment."
    }
    

    Returns all payments that were completed successfully in the specified cash up period. If a cash up period contains any pending payments we will return a HTTP 500. A cash up period is considered complete once we know the status of all the payments within the period. When we return a HTTP 500 due to pending payments you should wait a couple of seconds and then retry the request. See Cash Ups for further details.

    HTTP Request

    GET https://pos.snapscan.io/merchant/api/v1/payments/cash_ups/{reference}

    Route Parameters

    The reference route parameter is required.

    Parameter Description
    reference The cash up period's reference.

    Response Codes

    Description HTTP Status JSON Response
    OK 200 Array of payment objects
    Reference doesn't exist 404 Object containing a message key
    Pending payments 500 Object containing a message key

    Cash Ups

    The cash up API allows you to mark the end of your transaction period on our system. Once a transaction period has been marked you will be able to query all payments that were completed within the associated period. You can use the period's reference with the get cash up payments endpoint to retrieve the payments.

    The cash up object

    An example of a cash up object:

    {
      "date": "1999-12-31T23:00:00Z",
      "reference": "ab34Def78"
    }
    
    Attribute Type Description
    date String The UTC date of when the transaction period was ended. The date is ISO8601 formatted, eg: 1999-12-31T23:00:00Z
    reference String A hexadecimal string with a maximum length of 32.

    Create a cash up period

    curl -u your-api-key: -X POST "https://pos.snapscan.io/merchant/api/v1/cash_ups"
    

    The above command returns JSON structured like this:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "date": "1999-12-31T23:00:00Z",
      "reference": "1e07ac748d2627ba"
    }
    

    Returns a reference that marks the end of the current transaction period and the start of a new one. The reference can be used to retrieve all the payments that were successfully completed in the associated period.

    HTTP Request

    POST https://pos.snapscan.io/merchant/api/v1/cash_ups

    Response Codes

    Description HTTP Status JSON Response
    OK 200 A cash up object

    Get all cash ups

    curl -u your-api-key: "https://pos.snapscan.io/merchant/api/v1/cash_ups"
    

    The above command returns JSON structured like this:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
      {
        "date": "2000-01-01T12:00:00Z",
        "reference": "2f35cdc8246915c3"
      },
      {
        "date": "1999-12-31T23:00:00Z",
        "reference": "1e07ac748d2627ba"
      }
    ]
    

    Returns a paginated list of all cash up references that have been created. The references are ordered by descending date.

    HTTP Request

    GET https://pos.snapscan.io/merchant/api/v1/cash_ups

    Response Codes

    Description HTTP Status JSON Response
    OK 200 An array of cash up objects