Arrow

Developer paysafe

Authentication

For API integration you would append the specific endpoint to the base URLs listed on the right
All requests are authenticated against a particular entity using username, password and entityid.
Authentication data needs to be sent as POST parameters.
The Authentication object

Attributes
userid String The userId for the entity
password String The password for the userId
entityId string The entity for the request. By default this is the channel's ID
API Endpoints

TEST: /merchant/api
LIVE: https://ppay.io/merchant/api

{
  "Authentication": {
    "userid": "8a82941753851dxxxxx8c7f28511fb",
    "password": "sDFxxxxsNY",
    "entityid": "8a8294175385xxxxxx5388c89f9911fe"
  },

Errors

Peach Payments uses conventional HTTP response codes to indicate the success or failure of an API request.
In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.)
Not all errors map cleanly onto HTTP response codes. However, we include an error object for failed requests to provide more details on why the request failed.
The errors object

Attributes
userid string Error message regarding userid
password string Error message regarding password
entityId string Error message regarding entityid
commonerror string Error when authentication values missing/failed by using userid, password and entityid
payment.merchantinvoiceid string Error message regarding merchantInvoiceId
payment.amount string Error message regarding amount
payment.currency string Error message regarding currency
payment.emailcc string Error message regarding email_cc
payment.emailbcc string Error message regarding email_bcc
customer.givenname string Error message regarding givenName
customer.email string Error message regarding email
customer.mobile string Error message regarding mobile
userid string Error message regarding userid
password string Error message regarding password
entityid string Error message regarding entityid
HTTP status code summary
Attributes
userid String The userId for the entity
password String The password for the userId
entityId string The entity for the request. By default this is the channel's ID
Example error snippet
{
    "status": "failure",
    "errors": {
    "Customer": {
    "givenName": "Please enter first
    name",
    "mobile": "Only numbers are allowed"
    },
    "Payment": {
    "merchantInvoiceId": "Order No.
    should not be blank",
    "emailBcc": "Contains invalid email
    Ids"
    }
}

Generate a unique payment link for a transaction and optionally send this link to the recipient via email and/or sms.
The Authentication object

Attributes
amount string Payment amount
currency string The currency code of the payment request's amount (ISO 4217)
merchantinvoiceid string Your invoice / transaction / order Id
mode string Payment mode i.e Card or SID Instant EFT
sendEmail Boolean value, indicates whether send email to customer or not after creating payment.
sendSms Boolean value, indicates whether send sms to customer or not after creating payment.
emailCc (String) List of comma separated email ids.
emailBcc (String) List of comma separated email ids.
The customer object Attributes
givenname string The first name or given name of the customer
email string The customer's email address. Required for communicating with customer's regarding payment
mobile string The customer's mobile number. Required for communicating with customer's regarding payment. Format should be +27123456789
surname string The last name or surname of the customer
POST

/merchant/api/payments/generatePaymentLinkApi.json

Example Request
curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
  "Authentication": {
    "userid": "123456789123456789123456788511fb",
    "password": "asgftr1245",
    "entityid": "12345678912345678913456788511fb"
  },
  "Payment": {
    "merchantInvoiceId": "RHG45",
    "amount": 10,
    "currency": "ZAR",
    "files": [],
    "sendEmail": true,
    "sendSms": true,
    "emailCc": "check@test.com,trail@gmail.com",
    "emailBcc": ""
    "expiryTime":120,
    "notes":"checking demo"
  },
  "Customer": {
    "givenName": "abc",
    "surname": "efg",
    "email": "test12@gmail.com",
    "mobile": "123456789"
  }
}' "https://(domain name)"

Example Response
{
  "status": "success",
  "response": {
    "paymentId": "39",
    "url": "http://uat.ppay.io/Mzk="
  },
  "request": {
     "Payment": {
     "merchantInvoiceId": "RHG45",
     "amount": 10,
     "currency": "ZAR",
     "files": [],
     "sendEmail": true,
     "sendSms": true,
     "emailCc": "check@test.com,trail@gmail.com",
     "emailBcc": ""
     "expiryTime":120,
     "notes":"checking demo"
   },
  "Customer": {
     "givenName": "abc",
     "surname": "efg",
     "email": "test12@gmail.com",
     "mobile": "123456789"
   }
  }
}

You can cancel a previously generated link. To cancel a payment you will need to have the unique paymentId available. This is returned to you in the payment request.
The Authentication object

Attributes
userid string The userId for the entity
password string The password for the userId
entityId string The entity for the request. By default this is the channel's ID
The payment object Attributes
paymentId string The unique paymentID for the payment you would like to cancel
Example request
curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '
  {
 "Authentication": {
    "userid": "123456789123456789123456788511fb",
    "password": "asgftr1245",
    "entityid": "12345678912345678913456788511fb"
 },
 "Payment": {
   "paymentId": sugrwit457367ds
 }
}' "https://(domain name)"

Example Success Response
{
  "status": "success",
  "message": "Payment has been cancelled.",
  "response": {
    "paymentId": 1255
  },
  "request": {
    "Payment": {
      "paymentId": sugrwit457367ds
    }
  }
}
Example Failure Response

  "status": "failure",
  "errors": {
    "Payment": {
      "paymentId": "Please provide valid payment Id"
    }
  },
  "request": {
    "Payment": {
      "paymentId": "dummy"
    }
  }
}

Webhook

Webhook are HTTP call backs that deliver notification messages for events.

For our PaySafe platform we use Webhook to notify merchant systems when certain transaction events occur. This way your servers are always up to date with transaction information.

Once a webhook has been configured and verified – we will deliver POST notifications to the specified URL for the following events:

  1. Completed Payment – Triggers When a customer has successfully paid
  2. Cancelled Payment – Triggers when a payment request is canceled manually on the PaySafe portal

Workflow

  1. Merchants can register a webhook URL in the PaySafe portal
  2. Webhook are triggered for pre-defined events
  3. Merchant then triggers a query to pull transaction details and status

The body of the incoming POST notification contains the event object which contains the eventId to be used to query the transaction details.

Events

The event object

Attributes
eventId string Encoded eventId, it is use to identify an event
type string Event type
Values: PAYMENT.COMPLETED
PAYMENT.CANCELLED
Event[eventId]=abc1234df=&Event[type]=PAYMENT.COMPLETED&Event[testmode]=TRUE

Register a Webhook

  1. You can register a webhook URL in the PaySafe portal
    a. Log into www.ppay.io and navigate to the Settings>>Webhook page
  2. You will be required to receive an actual webhook and copy the embedded verification code
  3. The system will generate 10 digits long code, and send a POST request on above said URL with code data
  4. Your servers needs to respond with HTTP 200 status code to let us know you received the webhook
  5. Once the verification is complete the webhook will be active
{
"code" : "N(2840yES2"
}

Respond to the incoming webhook

Once your system receives a webhook, your server should respond with a HTTP status code of 200 to indicate that the webhook was successful.

If you respond with another status code, we consider the event delivery unsuccessful and the the PaySafe platform will try to deliver the webhook again.

Retries are sent at increasing time intervals until either the message is accepted or the maximum retry period of 5 days has been exceeded.

    Retry-intervals:
  1. 1 minute
  2. 2 minutes
  3. 4 minutes
  4. 8 minutes
  5. 15 minutes
  6. 30 minutes
  7. 1 hour
  8. every hour until 5 days have passed since the first attempt

If your server for receiving notifications was down for more than five days we will mark done the event.

Query transaction status

Once you have received the event.Id and type parameters from the incoming webhook, you must query our platform to retrieve the transaction details and status.
The Authentication object

Attributes
userid String The userId for the entity
password string The password for the userId
entityId string The entity for the request. By default this is the channel's ID

The event object

Attributes
eventId string Encoded eventId, it is use to identify an event
type string Event type
Values: PAYMENT.COMPLETED
PAYMENT.CANCELLED
Query Response

You will receive a Json response based on the outcome of the query and the transaction status.

The response data contains several objects which are included as required.

status success ; If payment url gets generated
failure ; If any error occurred
response json data Contains success response
request json data Contains request data excluding authentication parameters
The customer object Attributes
givenname string Customer given name
email string Customer email
mobile string Customer mobile
The payment object Attributes
amount string Payment amount
currency string Currency code of payment
merchantinvoiceid string Payment order number provided by merchant
transactionuniqueid string Transaction ID received by bank after payment
attachment string array of attachment like bills or documents
attachment[].name string attached file name
attachment[].url string attached file URL
mode string Payment mode i.e Card or SID Instant EFT
Example request
curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '
   {
  "Authentication": {
    "userid": "123456789123456789123456788511fb",
    "password": "asgftr1245",
    "entityid": "12345678912345678913456788511fb"
  },
  "Event": {
    "eventId": "ijkzddgMNjhPHrM=",
    "type": "PAYMENT.COMPLETED"
  }
}' "http://(domain name)"

Response Examples:
Response Samples
Completed Payment
{
  "status": "success",
  "response": {
    "Payment": {
      "amount": "44.00",
      "currency": "ZAR",
      "merchantInvoiceId": "djgfjhe6",
      "transactionUniqueId": "450bf3b1-c479-4b30-99ca-5b598a889b8f",
      "attachment": [
        {
          "name": "test.pdf",
          "url": "https://abc.com/test.pdf"
        },
        {
          "name": "demo.pdf",
          "url": "https://abc.com/demo.pdf"
        }
      ],
      "mode": "SID Instant EFT",
      "type": "API",
      "eventTimestamp": "2010-06-29 05:27:47",
      "registrationId" : "sdfsdfsdfsdfsdfds131232123"
    },
    "Customer": {
      "givenName": "Abc efd",
      "email": "abc@peachpayments.com",
      "mobile": "12347347637"
    }
  },
  "request": {
    "Event": {
      "eventId": "ijkzddgMNjhPHrM=",
      "type": "PAYMENT.COMPLETED"
    }
  }
}

Cancelled Payment
{
  "status": "success",
  "response": {
    "Payment": {
      "amount": "1,000.00",
      "currency": "ZAR",
      "merchantInvoiceId": "123456",
      "attachment": []
    },
    "Customer": {
      "givenName": "XYZ",
      "email": "xyz@peachpayments.com",
      "mobile": ""
    }
  },
  "request": {
    "Event": {
      "eventId": "QlJPxczKvr4=",
      "type": "PAYMENT.CANCELLED"
    }
  }
}

Error
{
  "status": "failure",
  "errors": {
    "eventId": "Please provide valid eventId",
    "type": "Please provide valid event type"
  },
  "request": {
    "Event": {
      "eventId": "",
      "type": ""
    }
  }
}