Back to top

PayMaya Bill Payments API Staging v1.0

Overview

PayMaya Bill Payments API makes it easy for Paymaya customers to pay their bills.

The API enables customers to pay for a wide suite of billers: utilities, cell phones, government, credit card companies, schools, governments, and a whole lot more.

Workflow

The API follows a 2-step "create and execute" approach in dealing with the bill payments.

The Create step requires the biller, bill amount, biller account number, and other biller related information. Once created, the API will return a bill payment reference number, along with the biller details summary, transaction fee and other details.

The next step Execute, in order to process the payment, is to invoke the Execute operation of the bill payment. This will set the bill payment for processing. Payment will be posted to the billers within 48 hours.

Payment Method

The API currently allows PayMaya Visa and Smart MasterCard cards as valid payment instruments. Only Card-Not-Present transactions are supported as of this time.

States

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.
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 biller was not successful due to either a client or server related error.

Figure 1 - Bill Payment Transaction States Diagram

Security

API Authentication

Bills Pay API require key-based authentication.

APIs and features accessible to each API consumer are defined by the public and/or secret key that the API consumer will use.

For each API call, the API consumer must pass an Authorization header (using Basic access authentication), with the API key encoded in Base64 MIME encoding.

Example:

Given secret key sk-A9zFq1siKCRREsF2nKG3wj2tfEkYNPO1bMt1nOxip9o:

Authorization: Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==

Biller List API

Billers

For full documentation, see Biller List API

List of Supported Billers
GET/billers

Example URI

GET /billers
Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: b8ead599-f8f9-46fb-9095-b1587078f9f8
Body
{
  "billers": [
    {
      "name": "Laguna Water",
      "slug": "LAGUNAWATER",
      "category": "Utilities",
      "listUrl": {
        "ios": {
          "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/3x/Category-Cignal@3x.png",
          "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/retina/Category-Cignal@2x.png"
        },
        "android": {
          "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/xhdpi/Category-Cignal.png",
          "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/mdpi/Category-Cignal.png",
          "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
        }
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "billers": {
      "type": "array",
      "description": "Array of billers available to the client."
    }
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Invalid key!"
}

Get a Specific Biller
GET/billers/{slug}

Example URI

GET /billers/slug
URI Parameters
HideShow
slug
string (required) 

slug of the biller

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
transaction-reference-no: 7266dbef-47b1-4051-a7cb-c72f1330ec0a
Body
{
  "biller": {
    "name": "Cignal Mediascape",
    "slug": "CIGNAL",
    "category": "Utilities",
    "categorySlug": "utilities",
    "otherFields": {
      "field": {
        "type": {
          "textfield": "Hello, world!",
          "selectable": "Hello, world!",
          "date": "Hello, world!",
          "hidden": "Hello, world!",
          "accountNumber": "Hello, world!",
          "amount": {
            "currency": "PHP",
            "value": "120"
          }
        },
        "regex": "^[-a-zA-Z .]{1,100}$",
        "required": "true",
        "placeholder": "First Name",
        "defaultValue": "BAYAD",
        "condition": {
          "field": "AccountType",
          "case": {
            "value": {
              "type": "textfield",
              "regex": "^[-a-zA-Z .]{1,100}$",
              "required": "true",
              "placeholder": "First Name",
              "defaultValue": "BAYAD",
              "visible": "true"
            }
          }
        },
        "visible": "true"
      }
    },
    "listUrl": {
      "ios": {
        "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/3x/Category-Cignal@3x.png",
        "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/ios/retina/Category-Cignal@2x.png"
      },
      "android": {
        "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/xhdpi/Category-Cignal.png",
        "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/mdpi/Category-Cignal.png",
        "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/list/android/hdpi/Category-Cignal.png"
      }
    },
    "confirmationUrl": {
      "ios": {
        "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/ios/3x/Confirmation-Cignal@3x.png",
        "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/ios/retina/Confirmation-Cignal@2x.png"
      },
      "android": {
        "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/xhdpi/Confirmation-Cignal.png",
        "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/mdpi/Confirmation-Cignal.png",
        "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/confirmation/android/hdpi/Confirmation-Cignal.png"
      }
    },
    "iconUrl": {
      "ios": {
        "3x": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/ios/3x/Dash-Cignal@3x.png",
        "retina": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/ios/retina/Dash-Cignal@2x.png"
      },
      "android": {
        "xhdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/xhdpi/Dash-Cignal.png",
        "mdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/mdpi/Dash-Cignal.png",
        "hdpi": "https://smi-dev.s3.amazonaws.com/mepay-acquiring/images/billers/staging/CIGNAL/icon/android/hdpi/Dash-Cignal.png"
      }
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "biller": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the biller"
        },
        "slug": {
          "type": "string",
          "description": "Unique identifier of the biller"
        },
        "category": {
          "type": "string",
          "description": "Category of the biller"
        },
        "categorySlug": {
          "type": "string",
          "description": "Unique identifier of the biller's category"
        },
        "otherFields": {
          "type": "object",
          "properties": {
            "field": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "object",
                  "properties": {
                    "textfield": {
                      "type": "string",
                      "description": "for alphanumeric and special characters"
                    },
                    "selectable": {
                      "type": "string",
                      "description": "a list of valid value will be indicated"
                    },
                    "date": {
                      "type": "string",
                      "description": "date in format of yyyy-MM-dd"
                    },
                    "hidden": {
                      "type": "string",
                      "description": "this may not be shown on user's input, its default value will be indicated"
                    },
                    "accountNumber": {
                      "type": "string",
                      "description": "a special type used to specify the Account Number to be paid"
                    },
                    "amount": {
                      "type": "object",
                      "properties": {
                        "currency": {
                          "type": "string",
                          "description": "Alpha Numeric country code"
                        },
                        "value": {
                          "type": "string",
                          "description": "Amount to be paid"
                        }
                      },
                      "description": "Contains the currency and amount to be paid"
                    }
                  },
                  "description": "type of the field"
                },
                "regex": {
                  "type": "string",
                  "description": "indicates the regular expression where the field with type text field will be validated"
                },
                "required": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ],
                  "description": "indicates if the field is required or not"
                },
                "placeholder": {
                  "type": "string",
                  "description": "the name of the field to be displayed"
                },
                "defaultValue": {
                  "type": "string",
                  "description": "required only when field type is hidden, this is always the field's value"
                },
                "condition": {
                  "type": "object",
                  "properties": {
                    "field": {
                      "type": "string",
                      "description": "the field where the condition will be matched"
                    },
                    "case": {
                      "type": "object",
                      "properties": {
                        "value": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": [
                                "textfield",
                                "selectable",
                                "date",
                                "hidden",
                                "accountNumber",
                                "amount"
                              ],
                              "description": "type of the field"
                            },
                            "regex": {
                              "type": "string",
                              "description": "indicates the regular expression where the field with type text field will be validated"
                            },
                            "required": {
                              "type": "string",
                              "enum": [
                                "true",
                                "false"
                              ],
                              "description": "indicates if the field is required or not"
                            },
                            "placeholder": {
                              "type": "string",
                              "description": "the name of the field to be displayed"
                            },
                            "defaultValue": {
                              "type": "string",
                              "description": "required only when field type is hidden, this is always the field's value"
                            },
                            "visible": {
                              "type": "string",
                              "enum": [
                                "true"
                              ],
                              "description": "indicates if the field should be visible or not."
                            }
                          },
                          "description": "value of the field to be matched"
                        }
                      },
                      "description": "an object where the key is the value of the field to be matched, and the value is an object which indicates properties of the field"
                    }
                  },
                  "description": "Indicates the condition when a field should be displayed or is required"
                },
                "visible": {
                  "type": "string",
                  "enum": [
                    "true"
                  ],
                  "description": "indicates if the field should be visible or not."
                }
              },
              "description": "Field specific only for the biller"
            }
          },
          "description": "An object of fields which are required by each biller"
        },
        "listUrl": {
          "type": "object",
          "properties": {
            "ios": {
              "type": "object",
              "properties": {
                "3x": {
                  "type": "string"
                },
                "retina": {
                  "type": "string"
                }
              },
              "description": "Icon URLs for iOS per screen resolution"
            },
            "android": {
              "type": "object",
              "properties": {
                "xhdpi": {
                  "type": "string"
                },
                "mdpi": {
                  "type": "string"
                },
                "hdpi": {
                  "type": "string"
                }
              },
              "description": "Icon URLs for Android per screen resolution"
            }
          },
          "description": "List of biller's icons/images to be displayed on initial screen"
        },
        "confirmationUrl": {
          "type": "object",
          "properties": {
            "ios": {
              "type": "object",
              "properties": {
                "3x": {
                  "type": "string"
                },
                "retina": {
                  "type": "string"
                }
              },
              "description": "Confirmation urls for ios per screen resolution"
            },
            "android": {
              "type": "object",
              "properties": {
                "xhdpi": {
                  "type": "string"
                },
                "mdpi": {
                  "type": "string"
                },
                "hdpi": {
                  "type": "string"
                }
              },
              "description": "Confirmation urls for android per screen resolution"
            }
          },
          "description": "List of biller's icons/images to be displayed upon confirmation of payment"
        },
        "iconUrl": {
          "type": "object",
          "properties": {
            "ios": {
              "type": "object",
              "properties": {
                "3x": {
                  "type": "string"
                },
                "retina": {
                  "type": "string"
                }
              },
              "description": "Icon urls for ios per screen resolution"
            },
            "android": {
              "type": "object",
              "properties": {
                "xhdpi": {
                  "type": "string"
                },
                "mdpi": {
                  "type": "string"
                },
                "hdpi": {
                  "type": "string"
                }
              },
              "description": "Icon urls for android per screen resolution"
            }
          },
          "description": "List of biller's icons/images to be displayed while paying"
        }
      },
      "description": "Details of the biller"
    }
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "logref": "90097fd6-b28a-4db9-b07a-53fa51767ce0",
    "message": "[2557] Biller Slug Does Not Exist",
    "links": [
      {
        "rel": "self",
        "href": "http://docs.paymayabillspaymentsapi.apiary.io/#reference/billers"
      }
    ]
  }
]

Bill Payments API

Bill Payments

Create
POST/bill-payments

Create a bill payment given a biller (using the slug), biller number, amount, and custom biller fields

Example URI

POST /bill-payments
Request
HideShow
Headers
Content-Type: application/json
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Request-Reference-No: 25F58996-0F4B-47BD-9026-575FC805226C
Body
{
  "biller": {
    "slug": "CIGNAL"
  },
  "requestMetadata": {
    "customFields": {
      "AccountNumber": "9007409850",
      "Amount": {
        "Currency": "PHP",
        "Value": 200
      },
      "FirstName": "ems",
      "LastName": "davos",
      "MI": "br",
      "ExternalEntityName": "BAYAD"
    }
  },
  "callback": {
    "url": "http://test-callback.com",
    "method": "POST",
    "metadata": {
      "headers": {}
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "biller": {
      "type": "object",
      "properties": {
        "slug": {
          "type": "string",
          "description": "identifies which biller will be paid"
        }
      },
      "description": "Contains biller details"
    },
    "requestMetadata": {
      "type": "object",
      "properties": {
        "customFields": {
          "type": "object",
          "properties": {},
          "description": "Fields that are specific only to the biller being paid. Biller's custom fields are returned upon request to Biller List API (see [Biller List API](http://docs.paymayabillerlistmanagementapi.apiary.io/)), they are the keys on `otherFields`."
        }
      },
      "description": "Contains additional information about the request"
    },
    "callback": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "url to be called"
        },
        "method": {
          "type": "string",
          "description": "HTTP Method to be used when calling the URL"
        },
        "metadata": {
          "type": "object",
          "properties": {
            "headers": {
              "type": "object",
              "properties": {}
            },
            "body": {
              "type": "object",
              "properties": {}
            }
          },
          "description": "contains custom headers and body that will be passed upon calling the callback"
        }
      },
      "description": "Contains information about the callback to be called upon change of state"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "billPaymentId": "b5961040-114b-4436-99fc-1998250d5969",
  "biller": {
    "slug": "CIGNAL",
    "accountNumber": "9007409850",
    "accountDetails": {
      "AccountName": "Juan Dela Cruz"
    },
    "name": "CIGNAL"
  },
  "receiptNumber": "Ym20190207015139123456789012",
  "amount": {
    "currency": "PHP",
    "value": "1500",
    "fees": {
      "total": {
        "currency": "PHP",
        "value": "120"
      },
      "breakdown": [
        {
          "description": "Pass-on Fee",
          "amount": {
            "currency": "PHP",
            "value": "120"
          }
        }
      ]
    }
  },
  "state": "NEW",
  "metaData": {
    "AccountName": {
      "placeholder": "Account Name",
      "type": "textfield"
    }
  },
  "createdAt": "2016-07-25T07:28:36.387Z",
  "updatedAt": "2016-07-25T07:28:36.387Z",
  "_links": {
    "self": {
      "href": "http://efs-financial-bills-payment-corp.staging.paymaya.com:60080/bill-payments"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "billPaymentId": {
      "type": "string",
      "description": "unique identifier of the billspay transaction"
    },
    "biller": {
      "type": "object",
      "properties": {
        "slug": {
          "type": "string",
          "description": "unique identifier of the biller"
        },
        "accountNumber": {
          "type": "string",
          "description": "account number to be paid"
        },
        "accountDetails": {
          "type": "object",
          "properties": {
            "AccountName": {
              "type": "string",
              "description": "Account name of user"
            }
          },
          "description": "Contains custom fields for biller"
        },
        "name": {
          "type": "string",
          "description": "name of the biller"
        }
      },
      "description": "Contains biller details"
    },
    "receiptNumber": {
      "type": "string",
      "description": "The receipt number of the transaction"
    },
    "amount": {
      "type": "object",
      "properties": {
        "currency": {
          "type": "string",
          "description": "Alpha Country Code"
        },
        "value": {
          "type": "string",
          "description": "Amount to be paid"
        },
        "fees": {
          "type": "object",
          "properties": {
            "total": {
              "type": "object",
              "properties": {
                "currency": {
                  "type": "string",
                  "description": "Alpha Numeric country code"
                },
                "value": {
                  "type": "string",
                  "description": "Amount to be paid"
                }
              },
              "description": "Indicates the total fee amount"
            },
            "breakdown": {
              "type": "array",
              "description": "Contains details of the fees added to the bill"
            }
          },
          "description": "Contains details about the additional amount to be paid"
        }
      },
      "description": "Contains the currency and amount to be paid"
    },
    "state": {
      "type": "string",
      "description": "indicates the current state of the transaction. *Refer to state diagram above"
    },
    "metaData": {
      "type": "object",
      "properties": {
        "AccountName": {
          "type": "object",
          "properties": {
            "placeholder": {
              "type": "string",
              "description": "Label in that will be displayed in app"
            },
            "type": {
              "type": "string",
              "description": "Type of field"
            }
          },
          "description": "field name"
        }
      },
      "description": "Serves as a descriptor for account details"
    },
    "createdAt": {
      "type": "string",
      "description": "indicates when the transaction was created"
    },
    "updatedAt": {
      "type": "string",
      "description": "indicated when the transaction was updated"
    },
    "_links": {
      "type": "object",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string"
            }
          },
          "description": "Self Links"
        }
      },
      "description": "HATEOAS Links"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "logref": "aac4d1e9-81c5-4180-9699-b8686e19608b",
    "message": "[2557] Biller Slug Does Not Exist",
    "links": [
      {
        "rel": "self",
        "href": "http://docs.paymayabillspaymentsapi.apiary.io/"
      }
    ]
  }
]

Execute
POST/bill-payments/{billpaymentid}/execute

Calling Execute sets the Bill Payment for processing. It will take 1 to 2 days before the actual payments gets processed.

Example URI

POST /bill-payments/{billpaymentid}/execute
Request  Bills Payment Card Not Present Transaction via Credit Card Format
HideShow
Headers
Content-Type: application/json
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Request-Reference-No: 25F58996-0F4B-47BD-9026-575FC805226C
Body
{
  "fundingInstrument": {
    "creditCard": {
      "expiryMonth": "06",
      "expiryYear": "2019",
      "number": "4834426573948123"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "fundingInstrument": {
      "type": "object",
      "properties": {
        "creditCard": {
          "type": "object",
          "properties": {
            "expiryMonth": {
              "type": "string",
              "description": "card's expiry month"
            },
            "expiryYear": {
              "type": "string",
              "description": "card's expiry year"
            },
            "number": {
              "type": "string",
              "description": "card number"
            }
          },
          "description": "Contains information about the card being used"
        }
      },
      "description": "Indicates which payment method is used"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "billPaymentId": "b5961040-114b-4436-99fc-1998250d5969",
  "biller": {
    "slug": "CIGNAL",
    "accountNumber": "9007409850",
    "accountDetails": {
      "AccountName": "Juan Dela Cruz"
    },
    "name": "CIGNAL"
  },
  "receiptNumber": "Ym20190207015139123456789012",
  "amount": {
    "currency": "PHP",
    "value": "1500",
    "fees": {
      "total": {
        "currency": "PHP",
        "value": "120"
      },
      "breakdown": [
        {
          "description": "Pass-on Fee",
          "amount": {
            "currency": "PHP",
            "value": "120"
          }
        }
      ]
    }
  },
  "state": "NEW",
  "metaData": {
    "AccountName": {
      "placeholder": "Account Name",
      "type": "textfield"
    }
  },
  "createdAt": "2016-07-25T07:28:36.387Z",
  "updatedAt": "2016-07-25T07:28:36.387Z",
  "_links": {
    "self": {
      "href": "http://efs-financial-bills-payment-corp.staging.paymaya.com:60080/bill-payments"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "billPaymentId": {
      "type": "string",
      "description": "unique identifier of the billspay transaction"
    },
    "biller": {
      "type": "object",
      "properties": {
        "slug": {
          "type": "string",
          "description": "unique identifier of the biller"
        },
        "accountNumber": {
          "type": "string",
          "description": "account number to be paid"
        },
        "accountDetails": {
          "type": "object",
          "properties": {
            "AccountName": {
              "type": "string",
              "description": "Account name of user"
            }
          },
          "description": "Contains custom fields for biller"
        },
        "name": {
          "type": "string",
          "description": "name of the biller"
        }
      },
      "description": "Contains biller details"
    },
    "receiptNumber": {
      "type": "string",
      "description": "The receipt number of the transaction"
    },
    "amount": {
      "type": "object",
      "properties": {
        "currency": {
          "type": "string",
          "description": "Alpha Country Code"
        },
        "value": {
          "type": "string",
          "description": "Amount to be paid"
        },
        "fees": {
          "type": "object",
          "properties": {
            "total": {
              "type": "object",
              "properties": {
                "currency": {
                  "type": "string",
                  "description": "Alpha Numeric country code"
                },
                "value": {
                  "type": "string",
                  "description": "Amount to be paid"
                }
              },
              "description": "Indicates the total fee amount"
            },
            "breakdown": {
              "type": "array",
              "description": "Contains details of the fees added to the bill"
            }
          },
          "description": "Contains details about the additional amount to be paid"
        }
      },
      "description": "Contains the currency and amount to be paid"
    },
    "state": {
      "type": "string",
      "description": "indicates the current state of the transaction. *Refer to state diagram above"
    },
    "metaData": {
      "type": "object",
      "properties": {
        "AccountName": {
          "type": "object",
          "properties": {
            "placeholder": {
              "type": "string",
              "description": "Label in that will be displayed in app"
            },
            "type": {
              "type": "string",
              "description": "Type of field"
            }
          },
          "description": "field name"
        }
      },
      "description": "Serves as a descriptor for account details"
    },
    "createdAt": {
      "type": "string",
      "description": "indicates when the transaction was created"
    },
    "updatedAt": {
      "type": "string",
      "description": "indicated when the transaction was updated"
    },
    "_links": {
      "type": "object",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string"
            }
          },
          "description": "Self Links"
        }
      },
      "description": "HATEOAS Links"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "logref": "7b711ae7-b687-40cf-b152-32e0f54037e5",
    "message": "[2561] Bill Payment ID was Already Processed",
    "links": [
      {
        "rel": "self",
        "href": "http://docs.paymayabillspaymentsapi.apiary.io/"
      }
    ]
  }
]

Execute - Push Payment
POST/bill-payments/{billpaymentid}/execute

Calling Execute sets the Bill Payment for processing. If Push Payment flag is set to ‘true’ the debiting of user wallet step via P3 will be skipped. It will take 1 to 2 days before the actual payments gets processed.

Example URI

POST /bill-payments/{billpaymentid}/execute
Request  For Push Payments no 'fundingInstrument' should be provided
HideShow
Headers
Content-Type: application/json
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Request-Reference-No: 25F58996-0F4B-47BD-9026-575FC805226C
Body
{
  "pushPayment": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "pushPayment": {
      "type": "boolean",
      "description": "Indicates that this is a Push Payment, should always be 'true'"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "billPaymentId": "b5961040-114b-4436-99fc-1998250d5969",
  "biller": {
    "slug": "CIGNAL",
    "accountNumber": "9007409850",
    "accountDetails": {
      "AccountName": "Juan Dela Cruz"
    },
    "name": "CIGNAL"
  },
  "receiptNumber": "Ym20190207015139123456789012",
  "amount": {
    "currency": "PHP",
    "value": "1500",
    "fees": {
      "total": {
        "currency": "PHP",
        "value": "120"
      },
      "breakdown": [
        {
          "description": "Pass-on Fee",
          "amount": {
            "currency": "PHP",
            "value": "120"
          }
        }
      ]
    }
  },
  "state": "AUTHORIZED",
  "metaData": {
    "AccountName": {
      "placeholder": "Account Name",
      "type": "textfield"
    }
  },
  "createdAt": "2016-07-25T07:28:36.387Z",
  "updatedAt": "2016-07-25T07:28:36.387Z",
  "_links": {
    "self": {
      "href": "http://efs-financial-bills-payment-corp.staging.paymaya.com:60080/bill-payments"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "billPaymentId": {
      "type": "string",
      "description": "unique identifier of the billspay transaction"
    },
    "biller": {
      "type": "object",
      "properties": {
        "slug": {
          "type": "string",
          "description": "unique identifier of the biller"
        },
        "accountNumber": {
          "type": "string",
          "description": "account number to be paid"
        },
        "accountDetails": {
          "type": "object",
          "properties": {
            "AccountName": {
              "type": "string",
              "description": "Account name of user"
            }
          },
          "description": "Contains custom fields for biller"
        },
        "name": {
          "type": "string",
          "description": "name of the biller"
        }
      },
      "description": "Contains biller details"
    },
    "receiptNumber": {
      "type": "string",
      "description": "The receipt number of the transaction"
    },
    "amount": {
      "type": "object",
      "properties": {
        "currency": {
          "type": "string",
          "description": "Alpha Country Code"
        },
        "value": {
          "type": "string",
          "description": "Amount to be paid"
        },
        "fees": {
          "type": "object",
          "properties": {
            "total": {
              "type": "object",
              "properties": {
                "currency": {
                  "type": "string",
                  "description": "Alpha Numeric country code"
                },
                "value": {
                  "type": "string",
                  "description": "Amount to be paid"
                }
              },
              "description": "Indicates the total fee amount"
            },
            "breakdown": {
              "type": "array",
              "description": "Contains details of the fees added to the bill"
            }
          },
          "description": "Contains details about the additional amount to be paid"
        }
      },
      "description": "Contains the currency and amount to be paid"
    },
    "state": {
      "type": "string",
      "description": "indicates the current state of the transaction. *Refer to state diagram above"
    },
    "metaData": {
      "type": "object",
      "properties": {
        "AccountName": {
          "type": "object",
          "properties": {
            "placeholder": {
              "type": "string",
              "description": "Label in that will be displayed in app"
            },
            "type": {
              "type": "string",
              "description": "Type of field"
            }
          },
          "description": "field name"
        }
      },
      "description": "Serves as a descriptor for account details"
    },
    "createdAt": {
      "type": "string",
      "description": "indicates when the transaction was created"
    },
    "updatedAt": {
      "type": "string",
      "description": "indicated when the transaction was updated"
    },
    "_links": {
      "type": "object",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string"
            }
          },
          "description": "Self Links"
        }
      },
      "description": "HATEOAS Links"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "logref": "7b711ae7-b687-40cf-b152-32e0f54037e5",
    "message": "[2561] Bill Payment ID was Already Processed",
    "links": [
      {
        "rel": "self",
        "href": "http://docs.paymayabillspaymentsapi.apiary.io/"
      }
    ]
  }
]

Check Status
GET/bill-payments/{billpaymentid}

Calling Check Status gives detailed information on the bill payment transaction’s current state

Example URI

GET /bill-payments/billpaymentid
URI Parameters
HideShow
billpaymentid
string (required) 

Bill Payment ID

Request
HideShow
Headers
Authorization: `Basic c2stQTl6RnExc2lLQ1JSRXNGMm5LRzN3ajJ0ZkVrWU5QTzFiTXQxbk94aXA5bw==`
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "billPaymentId": "b5961040-114b-4436-99fc-1998250d5969",
  "biller": {
    "slug": "CIGNAL",
    "accountNumber": "9007409850",
    "accountDetails": {
      "AccountName": "Juan Dela Cruz"
    },
    "name": "CIGNAL"
  },
  "receiptNumber": "Ym20190207015139123456789012",
  "amount": {
    "currency": "PHP",
    "value": "1500",
    "fees": {
      "total": {
        "currency": "PHP",
        "value": "120"
      },
      "breakdown": [
        {
          "description": "Pass-on Fee",
          "amount": {
            "currency": "PHP",
            "value": "120"
          }
        }
      ]
    }
  },
  "state": "NEW",
  "metaData": {
    "AccountName": {
      "placeholder": "Account Name",
      "type": "textfield"
    }
  },
  "createdAt": "2016-07-25T07:28:36.387Z",
  "updatedAt": "2016-07-25T07:28:36.387Z",
  "_links": {
    "self": {
      "href": "http://efs-financial-bills-payment-corp.staging.paymaya.com:60080/bill-payments"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "billPaymentId": {
      "type": "string",
      "description": "unique identifier of the billspay transaction"
    },
    "biller": {
      "type": "object",
      "properties": {
        "slug": {
          "type": "string",
          "description": "unique identifier of the biller"
        },
        "accountNumber": {
          "type": "string",
          "description": "account number to be paid"
        },
        "accountDetails": {
          "type": "object",
          "properties": {
            "AccountName": {
              "type": "string",
              "description": "Account name of user"
            }
          },
          "description": "Contains custom fields for biller"
        },
        "name": {
          "type": "string",
          "description": "name of the biller"
        }
      },
      "description": "Contains biller details"
    },
    "receiptNumber": {
      "type": "string",
      "description": "The receipt number of the transaction"
    },
    "amount": {
      "type": "object",
      "properties": {
        "currency": {
          "type": "string",
          "description": "Alpha Country Code"
        },
        "value": {
          "type": "string",
          "description": "Amount to be paid"
        },
        "fees": {
          "type": "object",
          "properties": {
            "total": {
              "type": "object",
              "properties": {
                "currency": {
                  "type": "string",
                  "description": "Alpha Numeric country code"
                },
                "value": {
                  "type": "string",
                  "description": "Amount to be paid"
                }
              },
              "description": "Indicates the total fee amount"
            },
            "breakdown": {
              "type": "array",
              "description": "Contains details of the fees added to the bill"
            }
          },
          "description": "Contains details about the additional amount to be paid"
        }
      },
      "description": "Contains the currency and amount to be paid"
    },
    "state": {
      "type": "string",
      "description": "indicates the current state of the transaction. *Refer to state diagram above"
    },
    "metaData": {
      "type": "object",
      "properties": {
        "AccountName": {
          "type": "object",
          "properties": {
            "placeholder": {
              "type": "string",
              "description": "Label in that will be displayed in app"
            },
            "type": {
              "type": "string",
              "description": "Type of field"
            }
          },
          "description": "field name"
        }
      },
      "description": "Serves as a descriptor for account details"
    },
    "createdAt": {
      "type": "string",
      "description": "indicates when the transaction was created"
    },
    "updatedAt": {
      "type": "string",
      "description": "indicated when the transaction was updated"
    },
    "_links": {
      "type": "object",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string"
            }
          },
          "description": "Self Links"
        }
      },
      "description": "HATEOAS Links"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "logref": "80614443-beef-4d0a-b867-7956a683badc",
    "message": "[2560] Bill Payment ID Does Not Exist",
    "links": [
      {
        "rel": "self",
        "href": "http://docs.paymayabillspaymentsapi.apiary.io/"
      }
    ]
  }
]

Callback API

Bill Payment Callback

Send Bill Payment Callback
GET/[Provided Billspay Callback URL]

Callback is a feature of Bills Pay API wherein a request type application/json is sent to the callback.url passed to the Create step. A Callback is sent whenever a change of State occurred, after the Processing state, on the Bills Pay transaction. This includes the following states:

  • Authorized

  • Posting Failed

  • Fulfilled

The client is responsible for ensuring that the callback URLs are valid and accessible from PayMaya’s Bills Pay API system, as well as the service hosting and handling the provided Callback URL is up and running.

Example URI

GET /[Provided Billspay Callback URL]
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "billPaymentId": "b5961040-114b-4436-99fc-1998250d5969",
  "biller": {
    "slug": "CIGNAL",
    "accountNumber": "9007409850",
    "name": "Cignal Mediascape"
  },
  "amount": {
    "currency": "PHP",
    "value": 200,
    "fees": {
      "total": {
        "value": "15.00",
        "currency": "PHP"
      },
      "breakdown": [
        {
          "description": "Pass on fee",
          "amount": {
            "value": "15.00",
            "currency": "PHP"
          }
        }
      ]
    }
  },
  "callback": {
    "url": "http://test-callback.com",
    "method": "POST",
    "metadata": {
      "headers": {}
    }
  },
  "state": "AUTHORIZED",
  "createdAt": "2016-07-25T07:28:36Z",
  "updatedAt": "2016-07-25T08:10:09Z",
  "links": []
}
Response  200
HideShow
Headers
Content-Type: application/json
Response  400
HideShow
Headers
Content-Type: application/json

Errors

Error Codes

Code Description
1996 Request is invalid; General error
1997 Client ID is Invalid/Client ID Does Not Exist
1999 Unable to parse response
2552 RRN is Empty/Invalid
2555 Category Slug Does Not Exist
2557 Biller Slug Does Not Exist
2559 Biller Account Number is Invalid
2560 Bill Payment ID Does Not Exist
2561 Bill Payment ID was Already Processed
2573 Callback URL is invalid
2574 Callback Method is invalid
2596 Generic Error for aggregator validations; Missing or invalid biller fields
2597 Biller Account Number Validation Timeout
2598 Database Timeout
2001 Declined - Refer to issuer
2005 Declined - Do not honor the transaction
2012 Invalid transaction
2013 Invalid amount
2014 Invalid card number
2051 Insufficient funds
2054 Expired card
2080 System currently not available
2089 Card Security Code/Card Verification Value is incorrect
2090 Issuer system inoperative
2096 Payment gateway system error
2098 Payment gateway encountered timeout

Generated by aglio on 22 Sep 2021