PayMaya Biller API Development v1.0

Overview ¶

Architecture and Integration

PayMaya Biller API enables Billers to accept cashless payments from their clients and subscribers through PayMaya’s BillsPay API.

Integration guidelines and requirements are enumerated in the following forms:

Integration Guidelines and Integration Form.

Figure 1 - Biller API Diagram

Bills Payment - States

States shows the current status of the Bills Payment transaction.

The States are determined by the actions of the Bills Payment API and the Partner API.

The States are only applicable after the ‘Validate Bills Payment’, since the transactions has not yet been created by Bills Payment API.

After ‘Validate Bills Payment’ the Bills Payment API invokes the ‘Post Bills Payment’ endpoint of the Partner Service.

During Posting, the Bills Payment API

creates the Bills Payment transaction
deducts the amount from the customer
and proceeds with posting the transaction to the Partner Service.

This section shows the State lifecycle as it is being processed by Paymaya Bills Payment API and the Partner Service.

State	Description
NEW	Bills Payment API Create was successful.
PROCESSING	Bills Payment API is currently processing the Bills Payment API Execute request.
AUTHORIZED	Bills Payment was successfully authorized by the payment facility involved during the Execute step.
POSTING	Bills Payment was successfully sent to the Partner Service.
FULFILLED	Bills Payment Transaction was fulfilled for settlement with the issuer and acquirer.
FAILED	Bills Payment was not successful due to either a client or server related error.
POSTING FAILED	Bills Payment Posting to Partner Service was not successful due to client or server-related error.

Figure 2 - Bills Payment Transaction States Diagram

Security ¶

Signature and Authorization

Biller API → Partner Service

Used by: VALIDATE BILLS PAYMENT & POST BILLS PAYMENT Requests

The Partner Service shall receive a request that has a header paymaya-signature whose value is a hash of the stringified request body, and is signed using the secret-key provided during the Biller Onboarding.

The paymaya-signature can be used by the Partner Service to verify if the request has not been tampered with.

Request-Reference-No: [RRN Value Here]
paymaya-signature: [Paymaya Signature]

Example Header in Incoming Paymaya Payment API Call

Paymaya Signature Cryptography

The hash & encoding to be used are as follows:

Hash: SHA256

Signature Encoding: Base64

We provided a tool for validating paymaya-signature received by the Partner Service.

Sample Codes for Signature Computation:

Language	Link	Description
NodeJS	Download	Requires at least NodeJS v8
Java	Download	Requires at least Java 8

Instruction in using the tool and sample data is in the README.md file.

Partner Service → Biller API

Used by: SEND POSTING CALLBACK Webhook Requests

The Partner Service shall send a webhook request for the callback to the Biller API.

The request is expected to have a HTTP basic access authentication.

The header field will be in the form of Authorization: Basic <credentials>. Wherein Basic indicates the authentication scheme, and <credentials> is the the Secret Key encoded in Base64.

Request-Reference-No: [RRN Value Here]
Authorization: `Basic (Secret key encoded in Base64)`

API ¶

The following API Endpoints are to be developed by the Partner.

These endpoints will need to be made available by the Partner Service for the Paymaya Biller API to handle Bills Payment.

Not all of the endpoints are mandatory to be implemented by the Partner.

Please use the matrix below as reference:

API Endpoint	Mandatory/Optional
Validate	M
Post	M
Inquire	O
Get Fee	O
Send Posting Callback	M

Validate ¶

Validate Bills Payment
POST`/v1/validate`

Paymaya Biller API → Partner Service

The Partner Service shall receive a request to validate if the details of the Bill Payment are correct, e.g. Account Number is invalid.

It is not recommended to persist or save this validation request in the database for the Partner Service. Treat this only as a validation request.

The result.code shall validate the Bills Payment details. If valid, the transaction shall be processed. Otherwise, the transaction shall be marked as FAILED and can no longer be reprocessed.

The table below enumerates the codes that the Biller API is expecting to receive upon validation. If the result.code's value is not 0000, then the result.message shall display an error message to the user given that the result.code is to be mapped. Otherwise, a generic error message shall be displayed.

The Mapped column indicates if the result.message requires mapping.

Response Code	Mapped back to customer?	Description	Sample Message `result.message`
0000	No	Bill payment details are valid. Customer may proceed with payment.	N/A
2559	Yes	Error message from response would be mapped back to customer in the app. Message is not customizable.	Account Number is invalid
2596	Yes	Error message from response would be mapped back to customer in the app.	Some example messages include: Amount is invalid MobileNo is invalid / required Billing data does not exist Bill is expired ReferenceNo is expired
ACQ018	No	Error message to be sent to MAYA for internal consumption only. Message is customizable. Should be descriptive to help Maya know the exact error for proper monitoring (ex. system errors)	Some example messages include: Maya signature mismatch. Biller cannot accept payments right now. Please try again later.

If in case the result.code value is not in the list of the valid values, the Bills Payment transaction shall be considered as invalid and shall be marked as FAILED.

Listed on table below are the format for each fields:

Request Field Format:

Name	Type	Length	Mandatory/ Optional	Description
id	String	N/A	M	Bills Payment Validation ID in UUID format (this is not the Bills Payment ID)
biller.accountNumber	String	Min=5, Max=30	M	Account number
biller.slug	String	N/A	M	Unique ID used by Bills Payment API
biller.fields	Map	N/A	M	Fields value may vary per biller
transaction.amount.currency	String	3	M	Amount currency
transaction.amount.value	Decimal	N/A	M	Amount value
transaction.date	Date	N/A	M	Timestamp with timezone format

Response 200 Field Format:

Name	Type	Length	Mandatory/ Optional	Description
id	String	N/A	M	Bills Payment Validation ID in UUID format (this is not the Bills Payment ID)
result.code	String	4	M	Result code
result.message	String	Min=1, Max=250	M	Result description
biller.accountNumber	String	Min=5, Max=30	M	Account number
biller.details	Map	N/A	M	Details value may vary per biller
transaction.amount.total.currency	String	3	O	Total currency
transaction.amount.total.value	Decimal	N/A	O	Total value
transaction.amount.base.currency	String	3	O	Base currency
transaction.amount.base.value	Decimal	N/A	O	Base value
transaction.amount.fee.currency	String	3	O	Fee currency
transaction.amount.fee.value	Decimal	N/A	O	Fee value
transaction.date	Date	N/A	M	Timestamp with timezone format

Response 400 Field Format:

Name	Type	Length	Mandatory/ Optional	Description
id	String	N/A	M	Bills Payment Validation ID in UUID format (this is not the Bills Payment ID)
date	Date	N/A	M	Timestamp with timezone format
result.code	String	4	M	Result code defined Mapped table
result.message	Map	N/A	M	Result description defined in Mapped table

Example URI

POST /v1/validate

Request

HideShow

Headers

Content-Type: application/json
Request-Reference-No: `1e9ac446-8a62-4ae3-852d-c352ceda99b`,
paymaya-signature: `wMUFXtp1v95MXVbJIWetWnGEmJ123abSWhzNRvKy12B/Y=`

Body

{
  "id": "76bd34ae-7d5d-47e8-a3d5-909410000168",
  "biller": {
    "accountNumber": "30655639",
    "slug": "BILLER",
    "fields": {
      "firstName": "John",
      "lastName": "Smith",
      "contactNumber": "+639384618830"
    }
  },
  "transaction": {
    "amount": {
      "currency": "PHP",
      "value": 100
    },
    "date": "2019-07-22T08:04:15.055Z"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identification of the Bill Payment validation request."
    },
    "biller": {
      "type": "object",
      "properties": {
        "accountNumber": {
          "type": "string",
          "description": "Account Number to be paid"
        },
        "fields": {
          "type": "object",
          "properties": {},
          "description": "Fields that are specific only to the biller being paid"
        }
      },
      "description": "Contains information about the bill to be paid"
    },
    "transaction": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "object",
          "properties": {
            "value": {
              "type": "number",
              "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
            },
            "currency": {
              "type": "string",
              "description": "Alpha Country Code"
            }
          },
          "description": "Contains information about the amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99).\n\ndate: `2019-07-22T08:04:15.055Z` (string) - Specifies the date and time when the request was sent"
        }
      },
      "description": "Contains information about the transaction"
    }
  }
}

Response 200

HideShow

Headers

Content-Type: application/json
Request-Reference-No: `1e9ac446-8a62-4ae3-852d-c352ceda99b`

Body

{
  "id": "76bd34ae-7d5d-47e8-a3d5-909410000168",
  "result": {
    "code": "0000",
    "message": "Successfully Validated."
  },
  "biller": {
    "accountNumber": "30655639",
    "details": {
      "firstName": "John",
      "lastName": "Smith",
      "contactNumber": "+639384618830"
    }
  },
  "transaction": {
    "amount": {
      "total": {
        "currency": "PHP",
        "value": 110
      },
      "base": {
        "currency": "PHP",
        "value": 100
      },
      "fee": {
        "currency": "PHP",
        "value": 10
      }
    },
    "date": "2019-07-22T08:04:15.055Z"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identification of the Bill Payment validation request."
    },
    "result": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "An AlphaNumeric code that indicates if the transaction was successful or not."
        },
        "message": {
          "type": "string",
          "description": "Description of `result.code`"
        }
      },
      "description": "Indicates if the Bill Payment is valid or not"
    },
    "biller": {
      "type": "object",
      "properties": {
        "accountNumber": {
          "type": "string",
          "description": "Account Number to be paid"
        },
        "details": {
          "type": "object",
          "properties": {},
          "description": "Additional Account Number details from the Biller."
        }
      },
      "description": "Contains information about the bill to be paid"
    },
    "transaction": {
      "type": "object",
      "properties": {
        "receiptNumber": {
          "type": "string",
          "description": "The receipt number of the transaction"
        },
        "amount": {
          "type": "object",
          "properties": {
            "total": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "number",
                  "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                },
                "currency": {
                  "type": "string",
                  "description": "Alpha Country Code"
                }
              },
              "description": "Total amount paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
            },
            "base": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "number",
                  "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                },
                "currency": {
                  "type": "string",
                  "description": "Alpha Country Code"
                }
              },
              "description": "Bill Payment amount. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
            },
            "fee": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "number",
                  "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                },
                "currency": {
                  "type": "string",
                  "description": "Alpha Country Code"
                }
              },
              "description": "Fee added on top of the Bill Payment amount. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
            }
          },
          "description": "Contains information about the amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
        },
        "date": {
          "type": "string",
          "description": "Specifies the date and time when the request was sent"
        }
      },
      "description": "Contains information about the transaction"
    }
  }
}

Response 400

HideShow

Headers

Content-Type: application/json
Request-Reference-No: `1e9ac446-8a62-4ae3-852d-c352ceda99b`

Body

{
  "id": "76bd34ae-7d5d-47e8-a3d5-909410000168",
  "date": "2019-07-22T08:04:15.055Z",
  "result": {
    "code": "2559",
    "message": "Account Number is invalid"
  }
}

Posting ¶

Post Bill Payment
POST`/v1/post`

Paymaya Biller API → Partner Service

The Partner Service shall receive the request to indicate that the customer’s account should be credited with the amount paid.

It is required for the Partner Service to persist this transaction request and manage the Bills Payment states. Post request always follows after a Bills Payment Validation request, there will be no Post request coming from Paymaya without Bills Payment Validation. Post request are thus considered already validated Bills Payment. The Partner Service can still re-validate the Bill Payment as an added security measure.

The table below enumerates the list of HTTP Status Codes the Biller API expects to receive.

HTTP Status Code	Description
2xx	The request was successfully received by the Biller and shall be queued for processing.
503, 504, 598, 599	A timeout has occurred. Once received, Biller API shall retry sending the request until it receives a successful response or reaches the maximum number of retries.
4xx, 5xx	A Client or Server error occurred. Once received, Biller API shall mark the request as POSTING FAILED.

Listed on table below are the format for each fields:

Request Field Format:

Name	Type	Length	Mandatory/ Optional	Description
id	String	N/A	M	Bill Payment ID in UUID format
biller.accountNumber	String	Min=5, Max=30	M	Account number
biller.slug	String	N/A	M	Unique ID used by Bills Payment API
biller.fields	Map	N/A	M	Fields value may vary per biller
transaction.amount.total.currency	String	3	M	Currency of transaction
transaction.amount.total.value	Decimal	N/A	M	Base + Fee of transaction
transaction.amount.base.currency	String	3	M	Currency of transaction
transaction.amount.base.value	Decimal	N/A	M	Base value of transaction
transaction.amount.fee.currency	String	3	O	Currency of transaction
transaction.amount.fee.value	Decimal	N/A	O	Fee value of transaction
transaction.date	Date	N/A	O	Timestamp with timezone format
callback.url	String	N/A	O	Callback url provided by PayMaya
callback.method	String	N/A	O	Http method(GET,POST, etc.)

Response with body 200 Field Format:

Name	Type	Length	Mandatory/ Optional	Description
id	String	N/A	M	Bill Payment ID in UUID format
result.code	String	4	M	Result code
result.message	String	Min=1, Max=250	M	Result description
biller.accountNumber	String	Min=5, Max=30	M	Account number
biller.details	Map	N/A	M	Details value may vary per biller
transaction.receiptNumber	String	Min=1, Max=250	M	Receipt number to be provided by biller
transaction.amount.total.currency	String	3	O	Total currency
transaction.amount.total.value	Decimal	N/A	O	Total value
transaction.amount.base.currency	String	3	O	Base currency
transaction.amount.base.value	Decimal	N/A	O	Base value
transaction.amount.fee.currency	String	3	O	Fee currency
transaction.amount.fee.value	Decimal	N/A	O	Fee value
transaction.date	Date	N/A	M	Timestamp with timezone format

Example URI

POST /v1/post

Request

HideShow

Headers

Content-Type: application/json
Request-Reference-No: `1e9ac446-8a62-4ae3-852d-c352ceda99b`,
paymaya-signature: `wMUFXtp1v95MXVbJIWetWnGEmJ123abSWhzNRvKy12B/Y=`

Body

{
  "id": "5e67d842-9638-4697-a61c-cbdeb7d14069",
  "biller": {
    "accountNumber": "30655639",
    "slug": "BILLER",
    "fields": {
      "firstName": "John",
      "lastName": "Smith",
      "contactNumber": "+639384618830"
    }
  },
  "transaction": {
    "amount": {
      "total": {
        "currency": "PHP",
        "value": 110
      },
      "base": {
        "currency": "PHP",
        "value": 100
      },
      "fee": {
        "currency": "PHP",
        "value": 10
      }
    }
  },
  "callback": {
    "url": "http://billspay-callback.com/{id}",
    "method": "POST"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identification of the Bill Payment validation request."
    },
    "biller": {
      "type": "object",
      "properties": {
        "accountNumber": {
          "type": "string",
          "description": "Account Number to be paid"
        },
        "fields": {
          "type": "object",
          "properties": {},
          "description": "Fields that are specific only to the biller being paid"
        }
      },
      "description": "Contains information about the bill to be paid"
    },
    "transaction": {
      "type": "object",
      "properties": {
        "receiptNumber": {
          "type": "string",
          "description": "The receipt number of the transaction"
        },
        "amount": {
          "type": "object",
          "properties": {
            "total": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "number",
                  "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                },
                "currency": {
                  "type": "string",
                  "description": "Alpha Country Code"
                }
              },
              "description": "Total amount paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
            },
            "base": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "number",
                  "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                },
                "currency": {
                  "type": "string",
                  "description": "Alpha Country Code"
                }
              },
              "description": "Bill Payment amount. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
            },
            "fee": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "number",
                  "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                },
                "currency": {
                  "type": "string",
                  "description": "Alpha Country Code"
                }
              },
              "description": "Fee added on top of the Bill Payment amount. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
            }
          },
          "description": "Contains information about the amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
        },
        "date": {
          "type": "string",
          "description": "Specifies the date and time when the request was sent"
        }
      },
      "description": "Contains information about the transaction"
    },
    "callback": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "specifies the url where the biller will send a callback request. `id` is the unique identification of the Bill Payment transaction (e.g. `76bd34ae-7d5d-47e8-a3d5-909410000168`)"
        },
        "method": {
          "type": "string",
          "description": "HTTP Method to be used when sending a callback"
        }
      },
      "description": "Contains information about the webhook"
    }
  }
}

Response 200

HideShow

Headers

Content-Type: application/json
Request-Reference-No: `1e9ac446-8a62-4ae3-852d-c352ceda99b`

Body

{
  "id": "5e67d842-9638-4697-a61c-cbdeb7d14069",
  "result": {
    "code": "0000",
    "message": "Successfully Posted."
  },
  "biller": {
    "accountNumber": "30655639",
    "details": {
      "firstName": "John",
      "lastName": "Smith",
      "contactNumber": "+639384618830"
    }
  },
  "transaction": {
    "receiptNumber": "Ym20190207015139123456789012",
    "amount": {
      "total": {
        "currency": "PHP",
        "value": 110
      },
      "base": {
        "currency": "PHP",
        "value": 100
      },
      "fee": {
        "currency": "PHP",
        "value": 10
      }
    },
    "date": "2019-07-22T08:04:15.055Z"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identification of the Bill Payment transaction."
    },
    "biller": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identification of the Bill Payment validation request."
        },
        "biller": {
          "type": "object",
          "properties": {
            "accountNumber": {
              "type": "string",
              "description": "Account Number to be paid"
            },
            "fields": {
              "type": "object",
              "properties": {},
              "description": "Fields that are specific only to the biller being paid"
            }
          },
          "description": "Contains information about the bill to be paid"
        },
        "transaction": {
          "type": "object",
          "properties": {
            "receiptNumber": {
              "type": "string",
              "description": "The receipt number of the transaction"
            },
            "amount": {
              "type": "object",
              "properties": {
                "total": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "number",
                      "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                    },
                    "currency": {
                      "type": "string",
                      "description": "Alpha Country Code"
                    }
                  },
                  "description": "Total amount paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                },
                "base": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "number",
                      "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                    },
                    "currency": {
                      "type": "string",
                      "description": "Alpha Country Code"
                    }
                  },
                  "description": "Bill Payment amount. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                },
                "fee": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "number",
                      "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                    },
                    "currency": {
                      "type": "string",
                      "description": "Alpha Country Code"
                    }
                  },
                  "description": "Fee added on top of the Bill Payment amount. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                }
              },
              "description": "Contains information about the amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
            },
            "date": {
              "type": "string",
              "description": "Specifies the date and time when the request was sent"
            }
          },
          "description": "Contains information about the transaction"
        },
        "callback": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "description": "specifies the url where the biller will send a callback request. `id` is the unique identification of the Bill Payment transaction (e.g. `76bd34ae-7d5d-47e8-a3d5-909410000168`)"
            },
            "method": {
              "type": "string",
              "description": "HTTP Method to be used when sending a callback"
            }
          },
          "description": "Contains information about the webhook"
        }
      },
      "description": "Contains information about the bill to be paid"
    },
    "transaction": {
      "type": "object",
      "properties": {
        "receiptNumber": {
          "type": "string",
          "description": "The receipt number of the transaction"
        },
        "amount": {
          "type": "object",
          "properties": {
            "total": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "number",
                  "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                },
                "currency": {
                  "type": "string",
                  "description": "Alpha Country Code"
                }
              },
              "description": "Total amount paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
            },
            "base": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "number",
                  "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                },
                "currency": {
                  "type": "string",
                  "description": "Alpha Country Code"
                }
              },
              "description": "Bill Payment amount. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
            },
            "fee": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "number",
                  "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                },
                "currency": {
                  "type": "string",
                  "description": "Alpha Country Code"
                }
              },
              "description": "Fee added on top of the Bill Payment amount. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
            }
          },
          "description": "Contains information about the amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
        },
        "date": {
          "type": "string",
          "description": "Specifies the date and time when the request was sent"
        }
      },
      "description": "Contains information about the transaction"
    },
    "callback": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "specifies the url where the biller will send a callback request. `id` is the unique identification of the Bill Payment transaction (e.g. `76bd34ae-7d5d-47e8-a3d5-909410000168`)"
        },
        "method": {
          "type": "string",
          "description": "HTTP Method to be used when sending a callback"
        }
      },
      "description": "Contains information about the webhook"
    }
  }
}

Response 400

HideShow

Headers

Content-Type: application/json

Inquire ¶

Inquire Transaction
GET`/v1/inquire/{id}`

Paymaya Biller API → Partner Service

The Partner Service will receive a request to verify the transaction’s status. Listed on the table below are the possible status expected to be returned upon inquiry.

Code	Status	Description
0000	FULFILLED	Transaction is already Posted
ACQ014	FAILED	A system error occurred while processing the transaction
ACQ015	POSTING FAILED	Transaction was not successfully posted
ACQ016	RECEIVED	Transaction was received and is queued for processing
ACQ017	NOT FOUND	Bills Payment does not exist

Listed on table below are the format for each fields:

Response with body 200 Field Format:

Name	Type	Length	Mandatory/ Optional	Description
id	String	N/A	M	Bill Payment ID in UUID format
result.code	String	4	M	Result code
result.message	String	Min=1, Max=250	M	Result description
biller.accountNumber	String	Min=5, Max=30	M	Account number
transaction.receiptNumber	String	Min=1, Max=250	M	Receipt number to be provided by biller
transaction.amount.total.currency	String	3	O	Total currency
transaction.amount.total.value	Decimal	N/A	O	Total value
transaction.amount.base.currency	String	3	O	Base currency
transaction.amount.base.value	Decimal	N/A	O	Base value
transaction.amount.fee.currency	String	3	O	Fee currency
transaction.amount.fee.value	Decimal	N/A	O	Fee value
transaction.date	Date	N/A	M	Timestamp with timezone format

Example URI

GET /v1/inquire/id

URI Parameters

HideShow

id: string (required)
Bill Payment ID

Request

HideShow

Headers

Content-Type: application/json
Request-Reference-No: `1e9ac446-8a62-4ae3-852d-c352ceda99b`

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": "5e67d842-9638-4697-a61c-cbdeb7d14069",
  "result": {
    "code": "0000",
    "message": "Successfully Posted"
  },
  "biller": {
    "accountNumber": "30655639"
  },
  "transaction": {
    "receiptNumber": "Ym20190207015139123456789012",
    "amount": {
      "total": {
        "currency": "PHP",
        "value": 110
      },
      "base": {
        "currency": "PHP",
        "value": 100
      },
      "fee": {
        "currency": "PHP",
        "value": 10
      }
    },
    "date": "2019-07-22T08:04:15.055Z"
  }
}

Get Fee ¶

Get Fee
GET`/v1/getFee`

Paymaya Biller API → Partner Service

The Partner Service will receive a request to retrieve fee.

Listed on the table below are the possible status expected to be returned upon retrieving fee.

HTTP Status Code	Description
2xx	The request was successfully received.
5xx	An Internal Server error occurred or timed out.

Response 200 Field Format:

Name	Type	Length	Mandatory/ Optional	Description
fee.value	String	N/A	M	Service fee of the biller
fee.currency	String	N/A	M	Currency

Example URI

GET /v1/getFee

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "fee": {
    "value": "10",
    "currency": "PHP"
  }
}

Webhook ¶

Webhook is a feature where the Partner Service will be able to send a real-time notification to Biller API to indicate if the Bill Payment was successfully processed or not.

Send Posting Callback
POST`/v1/billspay/{id}`

Partner Service → Paymaya Biller API

Biller API expects to receive at least one callback from the Partner Service for each Bills Payment transaction that was posted. If the Partner Service fails to send a callback, Biller API shall set the Bills Payment’s status to POSTING FAILED and shall reverse the payment to the user.

Callback Strategy

The Sending of Posting Callback can be handled by the Partner Service in two ways.

Strategy	Description	Notes
Live Posting	Callback is sent right after Posting	30 seconds delay is recommended after receiving and responding to the Post request. This assures that the Biller API is able to update the DB with the Post response for the Bills Payment.
Batch Posting	Callback is sent at a scheduled time	Once a day. This must be communicated during onboarding, expiration config must account for the scheduling, this affects settlement reports.

Partner Service Bills Payment Expiration Config

The Partner Service can set how long a Bills Payment can be considered as PROCESSING on their end. See table below for example:

Biller	Expiration	Transaction Date/Time	Expiration Date/Time
A	24 hours	08/14/2019 12:00PM	08/15/2019 12:00PM
B	12 hours	01/02/2019 1:00AM	01/02/2019 1:00PM
C	2 hours	06/12/2019 3:00PM	06/12/2019 5:00PM

Partner Service Result Codes

The table below lists the codes that Biller API expects to receive upon callback. If the result.code's value is not 0000, then the result.message shall be displayed to the user given that the result.code is to be mapped. Otherwise, a generic error message shall be shown. This is the same handling with Validate.

The Mapped column indicates if the result.message requires mapping.

Code	Mapped	Description
0000	N/A	Bills Pay was successfully posted
2559	Y	Account Number is invalid
2593	Y	[Field] is invalid / required
2596	N	Bill Payment does not exist
ACQ018	N	Generic Biller Validation Error

Biller API Response Status Codes

Upon receiving the callback, Biller API shall respond with the Status Codes listed on the table below.

HTTP Status Code	Description
2xx	The request was successfully received
5xx	An Internal Server error occurred. Once received, it is advised that the Partner Service retries sending the callback. There is no limit to the number of times a callback is sent.
4xx	A Client error occurred. Description of the error can be seen on the response’s `error.description`. It is advised that the Partner Service retry sending the request once the error is fixed on their end.

Biller API Response Error Codes

4xx Error Codes	Description
2596	Bills Payment is not found
2593	[Field] is invalid / required
ACQ019	General Biller System Error
ACQ020	Bills Payment is already expired
ACQ021	Bills Payment’s status is already fulfilled
ACQ022	Bills Payment Status is invalid (Not Posted)
1997	Authorization is invalid
1997	Authorization is expired
1997	Authorization does not have a scope

Partner Service Request Field Format

Listed on table below are the format for each fields:

Request Field Format:

Name	Type	Length	Mandatory/ Optional	Description
id	String	N/A	M	Bills Payment ID in UUID format
result.code	String	4	M	Result code
result.message	String	Min=1, Max=250	M	Result description
biller.accountNumber	String	Min=5, Max=30	M	Account number
biller.fields	Map	N/A	M	Fields value may vary per biller
transaction.receiptNumber	String	Min=1, Max=250	M	Receipt number to be provided by biller
transaction.amount.total.currency	String	3	M	Currency of transaction
transaction.amount.total.value	Decimal	N/A	M	Base + Fee of transaction
transaction.amount.base.currency	String	3	M	Currency of transaction
transaction.amount.base.value	Decimal	N/A	M	Base value of transaction
transaction.amount.fee.currency	String	3	O	Currency of transaction
transaction.amount.fee.value	Decimal	N/A	O	Fee value of transaction
transaction.otherInfo	String	N/A	O	Contains additional information about the posted transaction (e.g. transaction number, reference number, posting date)
transaction.date	Date	N/A	O	Timestamp with timezone format

Response Field Format:

Name	Type	Length	Mandatory/ Optional	Description
id	String	N/A	M	Bills Payment ID in UUID format
date	Date	N/A	M	Timestamp with timezone format
error.code	String	6	M	Error code
error.message	String	N/A	M	Error description

Example URI

POST /v1/billspay/id

URI Parameters

HideShow

id: string (required)
Bill Payment ID

Request

HideShow

Headers

Content-Type: application/json
Request-Reference-No: `1e9ac446-8a62-4ae3-852d-c352ceda99b`,
Authorization: `Basic (Secret Key encoded in Base64)`

Body

{
  "id": "76bd34ae-7d5d-47e8-a3d5-909410000168",
  "result": {
    "code": "0000",
    "message": "Successfully Posted"
  },
  "biller": {
    "accountNumber": "30655639"
  },
  "transaction": {
    "receiptNumber": "Ym20190207015139123456789012",
    "amount": {
      "total": {
        "currency": "PHP",
        "value": 110
      },
      "base": {
        "currency": "PHP",
        "value": 100
      },
      "fee": {
        "currency": "PHP",
        "value": 10
      }
    },
    "otherInfo": null,
    "date": "2019-07-22T08:04:15.055Z"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identification of the Bill Payment transaction."
    },
    "result": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "An AlphaNumeric code that indicates if the transaction was successful or not."
        },
        "message": {
          "type": "string",
          "description": "Description of `result.code`"
        }
      },
      "description": "Indicates if the Bill Payment was successfully posted or not"
    },
    "biller": {
      "type": "object",
      "properties": {
        "accountNumber": {
          "type": "string",
          "description": "Account Number that was paid"
        }
      },
      "description": "Contains information about the transaction"
    },
    "transaction": {
      "type": "object",
      "properties": {
        "receiptNumber": {
          "type": "string",
          "description": "A reference number generated by the 3rd party upon successful posting. This will serve as the customer's reference number when he/she calls the customer service for support."
        },
        "amount": {
          "type": "object",
          "properties": {
            "total": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "number",
                  "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                },
                "currency": {
                  "type": "string",
                  "description": "Alpha Country Code"
                }
              },
              "description": "Total amount paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
            },
            "base": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "number",
                  "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                },
                "currency": {
                  "type": "string",
                  "description": "Alpha Country Code"
                }
              },
              "description": "Bill Payment amount. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
            },
            "fee": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "number",
                  "description": "amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
                },
                "currency": {
                  "type": "string",
                  "description": "Alpha Country Code"
                }
              },
              "description": "Fee added on top of the Bill Payment amount. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
            }
          },
          "description": "Contains information about the amount to be paid. Can use integer or decimal rounded to 2 decimal places (ex: 9.99)."
        },
        "otherInfo": {
          "type": "object",
          "properties": {},
          "description": "Optional; Contains additional information about the posted transaction (e.g. transaction number, reference number, posting date)"
        },
        "date": {
          "type": "string",
          "description": "Specifies the date and time when the request was sent"
        }
      },
      "description": "Contains information about the transaction"
    }
  }
}

Response 200

HideShow

Headers

Content-Type: application/json
Request-Reference-No: `1e9ac446-8a62-4ae3-852d-c352ceda99b`

Body

{
  "id": "76bd34ae-7d5d-47e8-a3d5-909410000168",
  "date": "2019-07-22T08:04:15.055Z",
  "error": null
}

Response 400

HideShow

Headers

Content-Type: application/json
Request-Reference-No: `1e9ac446-8a62-4ae3-852d-c352ceda99b`

Body

{
  "id": "76bd34ae-7d5d-47e8-a3d5-909410000168",
  "date": "2019-07-22T08:04:15.055Z",
  "error": {
    "code": "0303",
    "message": "result.code is required"
  }
}

Errors ¶

4xx Error Codes

Error Codes	Description
2596	Bills Payment is not found
2559	Account Number is invalid
2593	[Field] is invalid / required
ACQ019	General Biller System Error
ACQ020	Bills Payment is already expired
ACQ021	Bills Payment is already fulfilled
ACQ022	Bills Payment is invalid (Not posted)
1997	Authorization is invalid
1997	Authorization is expired
1997	Authorization does not have a scope

Appendix ¶

Definition of terms

Clients - are devices that use Paymaya Bills Payment.

Bills Payment API or Billspay - this is an internal set of APIs that provides integration to the Paymaya App, which in turn allows clients to use the Billspay service.

Biller API - a set of APIs that allows partners to integrate to Paymaya Billspay.

Partner Service - this is the Biller integration usually done by partners, to integrate to Paymaya Billspay via the Biller API.

States - in Billspay, State is the state of the Bills Payment at one point in time during its lifecycle.

Authorization - Authorization is the function of specifying access rights/privileges to resources, which is related to information security and computer security in general and to access control in particular.

Secret Key - In secret key cryptography, the flow of data between two legitimate parties is encoded by a shared secret key.

Paymaya Signature - used by the Partner Service verify the validity of the request. Biller API will ‘sign’ the request, and the Partner Service will verify the signature.

Request Reference Number - is a unique identifier in UUID, this is used to identify the particular Bills Payment.

Hash(ing) - Hashing is generating a value or values from a string of text using a mathematical function. Hashing is one way to enable security during the process of message transmission when the message is intended for a particular recipient only.

Encoding - is the process of putting a sequence of characters (letters, numbers, punctuation, and certain symbols) into a specialized format for efficient transmission or storage.

Sha256 - stands for Secure Hash Algorithm – 256 bit and is a type of hash function commonly used in Blockchain. A hash function is a type of mathematical function which turns data into a fingerprint of that data called a hash.

Base64 - is a group of similar binary-to-text encoding schemes that represent binary data in an ASCII string format by translating it into a radix-64 representation.

Validate - Is a process in which the Biller API verifies the ‘validity’ of the Bills Payment with the Partner Service.

Post - Is a process in which the Biller API indicates to the Partner Service that the customer’s account should be credited with the amount in the Bills Payment.

Inquire - Is a process in which the Biller API can ask the Partner Service the current State of the transaction.

Fee - in the Biller API this is the service fee. Which is an amount indicating the cut of the biller for performing the transaction.

Callback - A webhook request initiated by the Partner Service to indicate the final State of the Bills Payment transaction (successful or not successful).

Test Tools

Link	Description
Download	Biller API Postman Collections. Requires Postman
Download	User Guide for Biller API Postman Collection

Overview ¶

Architecture and Integration ¶

Bills Payment - States ¶

Security ¶

Signature and Authorization ¶

Biller API → Partner Service ¶

Partner Service → Biller API ¶

API ¶

Validate ¶

Validate Bills PaymentPOST/v1/validate

Example URI

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Posting ¶

Post Bill PaymentPOST/v1/post

Example URI

Headers

Body

Schema

Headers

Body

Schema

Headers

Inquire ¶

Inquire TransactionGET/v1/inquire/{id}

Example URI

Headers

Headers

Body

Get Fee ¶

Get FeeGET/v1/getFee

Example URI

Headers

Body

Webhook ¶

Send Posting CallbackPOST/v1/billspay/{id}

Callback Strategy ¶

Partner Service Bills Payment Expiration Config ¶

Partner Service Result Codes ¶

Biller API Response Status Codes ¶

Biller API Response Error Codes ¶

Partner Service Request Field Format ¶

Example URI

Headers

Body

Schema

Headers

Body

Headers

Body

Errors ¶

4xx Error Codes ¶

Appendix ¶

Definition of terms ¶

Test Tools ¶

Architecture and Integration

Bills Payment - States

Signature and Authorization

Biller API → Partner Service

Partner Service → Biller API

Validate Bills Payment
POST`/v1/validate`

Post Bill Payment
POST`/v1/post`

Inquire Transaction
GET`/v1/inquire/{id}`

Get Fee
GET`/v1/getFee`

Send Posting Callback
POST`/v1/billspay/{id}`

Callback Strategy

Partner Service Bills Payment Expiration Config

Partner Service Result Codes

Biller API Response Status Codes

Biller API Response Error Codes

Partner Service Request Field Format

4xx Error Codes

Definition of terms

Test Tools