Endpoints

The API offers a few endpoints to allow for flexible queries of Payjoy data.

In this section you will find a list of all queries available using the PayJoy API.

List Clerks

Query:

curl 'https://partner.payjoy.com/v1/list-clerks.php?key=<apikey>'

Result:

{"valid":true,"clerks":[
  {"id":"5335","name":"DemoClerk1","phoneNumber":"16178994187","email":"demo1@clerk.com"},
  {"id":"5334","name":"DemoClerk","phoneNumber":"16178994187","email":"test1@clerk.com"},
  {"id":"5320","name":"Demo InstallClark","phoneNumber":"16178994187","email":"demo1@clerk.com"}
]}

List Merchants

Query:

curl 'https://partner.payjoy.com/v1/list-merchants.php?key=<apikey>'

Result:

{"valid":true,"merchants":[
  {"id":"851005","name":"DEMO","address":
    {"street":"679 3rd St","street2":null,"city":"Tallahassee","state":"FL",
    "postalCode":"","country":"US"},"phoneNumber":"555-555-5555"},
  {"id":"999888","name":"DEMO1","address":
    {"street":"55 E 3rd Ave","street2":null,"city":"San Mateo","state":"CA",
    "postalCode":"94401","country":"US"},"phoneNumber":"505-505-5055"},
  {"id":"1000201","name":"DEMO2","address":
    {"street":"679 3rd St","street2":null,"city":"San Francisco","state":"CA",
    "postalCode":"94107","country":"US"},"phoneNumber":"555-555-5555"}
]}

Lookup Customer

Query:

curl 'https://partner.payjoy.com/v1/lookup-customer.php?key=<apikey>&customerLocator=<customerLocator>'

Note

  • customerLocator should be the customer’s phone number OR device tag OR an imei.
  • An imei is composed of decimal digits only, and may be 15 or 16 digits long.

Result:

{ "valid": true,
  "customer": {
    "id": 4000005
    },
    "device": {
    "validThrough": 1560679200,
    "family": { "id": 3, "name": "Galaxy S6"},
    "imei": "339977",
    "model": {"id": 3, "makeModel": "SAMSUNG SM-G920P", "name": "Samsung Galaxy S6 (Boost/Sprint)"},
    "simNumber": "12345678901774567891",
    "lastSeen": 1560679200,
    "secureStatus": "Device Active And Secured"
  },
  "financeOrder": { "currency": "USD", "downPayment": 100, "financeAmount": 200, "id": 4000004,
    "monthlyCost": 18, "months": 12, "pricePreTax": 300, "purchaseAmount": 300,
    "remainingBalance": 198, "time": 1482000000, "weeklyCost": 4},
  "paymentHistory": [
    {"amount": "18.00", "currency": "USD", "timestamp": "1487000002"}
  ],
  "paymentOptions": [
    {"amount": 198,"currency": "USD","type": "full"},
    {"amount": 18,"currency": "USD","type": "month"},
    {"amount": 4,"currency": "USD","type": "week"}
  ]
}

Lookup Cart

  • key Your private PayJoy partner API key. This parameter is required.
  • cartTag Cart tag that you are looking for. This parameter is required.

Query:

curl 'https://partner.payjoy.com/v1/lookup-cart.php?key=<apikey>&cartTag=<cartTag>'

Result:

{
  "valid": true,
  "customer": {
    "id": "11234",
    "name": "API User",
    "phoneNumber": "9991234567"
  },
  "cart": {
    "cartTag": "CARTTAGDEMO",
    "purchaseAmount": "3200.00",
    "financeAmount": "2156.00",
    "downPayment": "1044.00",
    "pricePreTax": 3000,
    "monthlyCost": "559.00",
    "weeklyCost": "129.00",
    "months": "6",
    "currency": "MXN"
  },
  "device": {
    "family": "Grand Prime Plus",
    "makeModel": "SAMSUNG SM-G532M"
  }
}

List Transactions

Query:

curl 'https://partner.payjoy.com/v1/list-transactions.php?\
     key=<apikey>&starttime=<starttime>&endtime=<endtime>'

Result:

{
  "valid":true,
  "transactions":[
  {
    "type":"finance",
    "time":1482000000,
    "amount":200,
    "currency":"USD",
    "financeOrder":{"id":4000004,"purchaseAmount":300,
        "financeAmount":200,"downPayment":100,"pricePreTax":300,
        "monthlyCost":18,"weeklyCost":4,"months":12},
    "merchant":{"id":4000002,"name":"API Test Merchant"},
    "salesClerk":{"id":4000003,"name":"Demo Clerk1"},
    "customer":{"id":4000005,"name":"API User","phoneNumber":"14084930580"},
    "device":{
      "phoneNumber":"15052111315",
      "simNumber":"12345678901774567891",
      "imei":"339977",
      "family":{"id":3,"name":"Galaxy S6"},
      "model":{"id":3,"makeModel":"SAMSUNG SM-G920P",
        "name":"Samsung Galaxy S6 (Boost\/Sprint)"}
    }
  },
  {
    "type":"cash",
    "time":1487000002,
    "amount":-18,
    "currency":"USD",
    "payment":{
        "id":4000008,
        "timestamp":1487000002,
        "amount":18},
    "financeOrder":{"id":4000004},
    "merchant":{
        "id":4000002,
        "name":"API Test Merchant"},
    "salesClerk":{
        "id":4000003,
        "name":"Demo Clerk1"},
    "customer":{
        "id":4000005,
        "name":"API User",
        "phoneNumber":"14084930580"}
  },
  {
    "type":"commission",
    "time":1602189749,
    "amount":1.8,
    "currency":"USD",
    "payment":{
        "id":5928003,
        "timestamp":1602189748,
        "amount":222},
    "financeOrder":{"id":4000004},
    "merchant":{
        "id":4000002,
        "name":"API Test Merchant"}
  },
  {
    "type":"adjustment",
    "time":1611085486,
    "amount":18,
    "currency":"USD",
    "adjustment":{
        "id":8884,
        "type":"payment",
        "notes":"Return adjustment for payment: 4000008"},
    "merchant":{
        "id":4000002,
        "name":"API Test Merchant"}
  },
  {
    "type":"adjustment",
    "time":1611085490,
    "amount":-1.8,
    "currency":"USD",
    "adjustment":{
        "id":8885,
    "type":"commission",
    "notes":"Return commission adjustment for payment: 4000008"},
    "merchant":{
        "id":4000002,
        "name":"API Test Merchant"}
  }]
}

Record In-Store Payment

  • key Your private PayJoy retail API key. This parameter is required.
  • merchantId PayJoy merchant unique identifier. A list of all stores can be found using the “List Merchants” endpoint. This parameter is required.
  • salesClerkId PayJoy clerk unique identifier. A list of all clerks can be found using the “List Clerks” endpoint. This parameter is required.
  • financeOrderId PayJoy unique identifier for the client’s contract. Customer information can be found using the “Lookup Customer” endpoint. This parameter is required.
  • amount The payment amount. This parameter is required.
  • currency ISO currency code. This parameter is required.

Query:

curl 'https://sandbox.payjoy.com/api/partner/v1/record-customer-payment.php?\
key=abcde_fghij_dKktCpNrQSzm1_4coilc&merchantId=91234567&salesClerkId=1001234&\
financeOrderId=4001234&amount=4&currency=USD'

Result:

{
  "valid": true,
  "payment": {
    "id": "<integer, guaranteed to be unique>",
    "time": "<unix timestamp when payment was recorded>",
    "deviceTag": "<deviceTag of the device that received credit for the payment>",
    "remainingBalance": "<amount the customer needs to pay before the device is fully paid off>",
    "currency": "<currency of the remaining balance>",
    "nextPayment": "<unix timestamp when the device's lock will activate if payment is not received>",
    "fullyPaid": "<true if the device has been fully paid, false if a balance remains>"
  }
}

List Collections

Collections are devices with an active finance order that are late in his payments a.k.a. validThrough is past of the current date. The list will return information from today to a year ago.

  • key Your private PayJoy retail API key. This parameter is required.
  • starttime:endtime The time window to look for devices validthrough timestamp. The parameter is optional and will retrieve information from a year from now if not sent.
  • merchantids List of PayJoy merchant unique identifier. Could send a coma separated list of mercahntId’s. This parameter is optional.

Query:

starttime=1569010227
endtime=1569020227
merchantids=195886,195264
curl 'https://partner.payjoy.com/v1/list-collections.php?\
    key=<apikey>&starttime=<starttime>&endtime=<endtime>&merchantids=<merchantids>'

Result:

{
  "valid":true,
  "collections":[
    {
    "userId": "999942",
    "name": "name999942",
    "validThrough": "2019-09-20",
    "merchantName": "Financed Store 195886",
    "merchantId": "195886"
},
{
    "userId": "99911",
    "name": "name99911",
    "validThrough": "2019-09-20",
    "merchantName": "Financed Store 195886",
    "merchantId": "195886"
},
{
    "userId": "99974",
    "name": "name99974",
    "validThrough": "2019-09-20",
    "merchantName": "Financed Store 195886",
    "merchantId": "195886"
},
{
    "userId": "306336",
    "name": "name306336",
    "validThrough": "2019-09-20",
    "merchantName": "Macro Financed Hunucma",
    "merchantId": "195264"
}]
}