POSaBIT Pay API Documentation

Updated 15 hours ago

Overview

The POSaBIT Pay API facilitates secure payment processing for consumers. It supports both BASIC and BEARER authorization schemes, allowing merchants to verify consumers, handle sign-ins, and process payments efficiently.

Authorization

Supported Authorization Schemes

1. Basic Authorization
   1. Type/Scheme: Basic
   2. Credentials (Base64 encoded): Base64(ClientId:ClientSecret)
2. Bearer Authorization
   1. Type/Scheme: Bearer
   2. Credentials: OAuthAccessToken

API Endpoints

Base URLs

• Test Environment: https://tst-api.hypur.com/merchants
• Production Environment: https://api.hypur.com/merchants

Authentication URLs

• Sign In:
  • Test Environment: https://tst-api.hypur.com/oauth/authorize?client_id=<CLIENT_ID>&response_type=code&scope=<SCOPE>&redirect_uri=<REDIRECT_URI>&state=<STATE>
  • Production Environment: https://api.hypur.com/oauth/authorize?client_id=<CLIENT_ID>&response_type=code&scope=<SCOPE>&redirect_uri=<REDIRECT_URI>&state=<STATE>
• Sign Up:
  • Test Environment: https://test.hypur.com/SignUp
  • Production Environment: https://secure.posabit.com/SignUp

API Workflow

1. Consumer Verification: Determine if a consumer has a POSaBIT Pay profile and  send OTP.
2. Consumer Sign-Up: If no profile exists, provide a sign-up link.
3. Consumer Sign-In: Obtain OAuth Access Token.
4. Consumer Payment: Process payments using an OAuth token and PIN.

API Endpoint Details

Consumer Verification (/consumer/verify)

Request

• Method: POST
• Authorization: BASIC <Base64(ClientId:ClientSecret)>
• Parameters:

{
    "MerchantToken": "<Required, MaxLength(50)>",
    "Phone": "<Required, MaxLength(10)>",
    "SendSms": false,
    "SendOtp": false
}

Response: Success

{
    "HasProfile": true,
    "HasBankAccount": true,
    "SmsSent": false,
    "Consumer": {
        "Id": 123,
        "FirstName": "John"
    },
    "Success": true,
    "RequestId": "abc123",
    "Error": null
}

Response: Error

{
    "Success": false,
    "RequestId": "abc123",
    "Error": {
        "Message": "Invalid request",
        "Name": "ValidationError",
        "Code": 400
    }
}

HTTP Status Codes:

• 200 OK: Success
• 400 Bad Request: Error in request

Consumer Sign-In (/consumer/sign-in)

Request

• Method: POST
• Authorization: BASIC <Base64(ClientId:ClientSecret)>
• Parameters:

{
    "MerchantToken": "<Required, MaxLength(50)>",
    "Phone": "<Required, MaxLength(10)>",
    "OTP": "<Required, MaxLength(4)>",
    "OAuthScope": "<Required>"
}

Response: Success

{
    "OAuthAccessToken": "token123",
    "Consumer": {
        "Id": 123,
        "FirstName": "John"
    },
    "Success": true,
    "RequestId": "xyz456",
    "Error": null
}

Response: Error

{
    "Success": false,
    "RequestId": "xyz456",
    "Error": {
        "Message": "Invalid OTP",
        "Name": "AuthenticationError",
        "Code": 400
    }
}

HTTP Status Codes:

• 200 OK: Success
• 400 Bad Request: Error in request

Consumer Payment (/payments/consumer)

Request

• Method: POST
• Authorization: BEARER <OAuthAccessToken>
• Parameters:

{
    "MerchantToken": "<Required, MaxLength(50)>",
    "PIN": "<Required, MaxLength(4)>",
    "PurchaseAmount": 100.50,
    "ConsumerPaidFeeAmount": 2.50,
    "TipAmount": 5.00,
    "TipOfferShown": true,
    "Note": "Payment for order #12345"
}

Response: Success

{
    "Id": 789,
    "TrackingId": "trk567",
    "Success": true,
    "RequestId": "def789",
    "Error": null
}

Response: Error

{
    "Success": false,
    "RequestId": "def789",
    "Error": {
        "Message": "Insufficient funds",
        "Name": "PaymentError",
        "Code": 400
    }
}

HTTP Status Codes:

• 200 OK: Success
• 400 Bad Request: Error in request

Related Articles

• POSaBIT POS API Documentation
• POSaBIT Pay Reports
• POSaBIT Pay - UPDATE CREDENTIALS

How did we do?