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

API Endpoints

TEST: https://test.ppay.io/merchant/api/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

HTTP status code summary

Generate Link

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

POST

https://test.ppay.io/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"
   }
  }
}

Cancel Link

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

POST

https://test.ppay.io/merchant/api/payments/cancelPaymentApi.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": {
   "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

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

POST

https://test.ppay.io/merchant/api/payments/getActivityDetail.json

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": ""
    }
  }
}