### Maya Callback API Interaction Guide

Source: https://developers.maya.ph/docs/biller-api-local-development-mock-testing

Explains the purpose and usage of Maya's Callback API as demonstrated by the provided Postman collection. It clarifies that the endpoints are for mock testing purposes only and do not interact with live systems, serving solely as a guide for correct API calling patterns.

```APIDOC
Maya's Callback API:
  Purpose: To inform Maya about the status of a bill payment.
  Usage Guide: Refer to the Local Development Mock Testing Postman collection.
  Endpoint Type: Mock endpoints provided in Postman collection.
  Note: Calls to these mock endpoints do not reach Maya's actual system; they serve as a guide for correct API calling.
```

--------------------------------

### Online Payments Overview

Source: https://developers.maya.ph/docs/sandbox-credentials-and-cards-guide

Provides an overview of the online payment system, including quickstart guides, business rules, sandbox credentials, payment statuses, voids, refunds, and API request limits.

```APIDOC
Online payments:
  Quickstart on Online Payments: /reference/how-to-try-our-online-payment-endpoints
  How to Try Our Online Payment Endpoints: /reference/how-to-try-our-online-payment-endpoints
  Business Rules to Code for Online Payments: /reference/business-rules-to-code-for-online-payments
  Sandbox Credentials and Cards: /reference/sandbox-credentials-and-cards
  Payment Statuses: /reference/payment-statuses
  Voids and Refunds: /reference/vids-and-refunds
  Limits on API Requests: /reference/limits-on-api-requests
```

--------------------------------

### Generate GPG Key via Command Line

Source: https://developers.maya.ph/docs/gpg-guide

Execute this command in your root/home directory to initiate the GPG key generation process. It will guide you through selecting key type, size, expiration, user ID, and passphrase.

```Shell
gpg --full-generate-key
```

--------------------------------

### Maya Biller API Post Endpoint Overview

Source: https://developers.maya.ph/docs/biller-api-sandbox-integration-testing

Details the purpose and expected behavior of the Partner's Biller Post Endpoint, which receives bill details, amount, fee, and a callback URL. It also highlights an important note regarding the callback URL for sandbox testing.

```APIDOC
Endpoint: Partner's Biller Post Endpoint
Purpose: Receives a Post Bill Request
Request Body Includes:
  - bill details
  - amount
  - fee
  - callback URL
Scenarios:
  - Successful Post Endpoint:
    - Description: Happy path testing for post endpoint.
    - Important Note: Callback URL generated from Postman request should be disregarded. A different callback URL with a generated Bill Payment ID from Maya’s Biller SBX service will be sent to the biller’s post-service API. This persisted callback URL will be usable for Callback Testing.
  - Declined Post Endpoint - Invalid Paymaya Signature:
    - Description: Used to test a Failed Posting scenario during Callback.
```

--------------------------------

### Payments Processing Platform APIs and Guides

Source: https://developers.maya.ph/docs/recurring-wallet-payments

This section covers the APIs for the Payments Processing Platform, including initial setup guidance, sandbox test credentials, and error handling. It details various payment and authorization operations such as pay, authorize, capture, void, refund, and balance inquiry, as well as transaction retrieval methods.

```APIDOC
Payments Processing Platform:
  Know before you code
  Sandbox Test Credentials and Cards for Payments Processing Platform
  Payments Processing Platform Errors
  Payments and Authorizations:
    Paypost
    Authorizepost
    Capturepost
    Final Capturepost
    Voidpost
    Refundpost
    Account Balance Inquirypost
  Transaction Retrieval:
    Get Transactionget
    List Transactionget
  Utilities:
    Service Pingget
```

--------------------------------

### Maya GPG Guide Documentation

Source: https://developers.maya.ph/docs/shopify

Refer to the General Payment Gateway (GPG) guide for comprehensive information on payment processing.

```APIDOC
https://developers.maya.ph/docs/gpg-guide
```

--------------------------------

### Sample Payment Link

Source: https://developers.maya.ph/docs/payment-links

An example of a generated Maya Payment Link for a sandbox environment, demonstrating the structure with a specific merchant alias.

```URL
https://sandbox.mymaya.me/SbxInv
```

--------------------------------

### Maya Biller API Callback Endpoint Overview

Source: https://developers.maya.ph/docs/biller-api-sandbox-integration-testing

Describes the Partner Biller's endpoint for sending callbacks to Maya for each posted bill payment transaction. It outlines the expected behavior for successful and failed posting callbacks, including specific result codes and data fields.

```APIDOC
Endpoint: Partner Biller's Callback Endpoint
Purpose: Notifies Maya whether bill payment transactions have been successfully posted on the biller’s end.
Behavior: Sends at least one (1) callback to Maya for each posted bill payment transaction.
Scenarios:
  - Successful Callback Biller API:
    - Description: Happy path testing for callback endpoint assuming the biller would be notifying Maya that the bill payment made has already been posted on their end.
    - result.code: 0000
    - transaction.receiptNumber: Should be a valid identifier on the biller’s end.
    - Usage: This request uses the Bill Payment ID generated from the previous Successful Post Endpoint request.
  - Successful Callback Biller API - For Failed Posting:
    - Description: Happy path testing for callback endpoint assuming biller would be notifying Maya that the bill payment made has failed to post on their end.
    - result.code: Should NOT be 0000.
    - result.message: Should indicate a concise reason why the posting failed on the biller’s end.
    - transaction.receiptNumber: Should be a valid identifier on the biller’s end.
    - Usage: This request uses the Bill Payment ID generated from the previous Successful Post Biller API - For Failed Posting Callback request.
```

--------------------------------

### Sample Payment Link with Pre-filled Amount

Source: https://developers.maya.ph/docs/payment-links

An example of a Maya Payment Link with a pre-filled transaction amount (100) for a sandbox environment, illustrating how to use the `?amt={amount}` parameter.

```URL
https://sandbox.mymaya.me/SbxInv?amt=100
```

--------------------------------

### Maya Vault Integration Setup and Authentication

Source: https://developers.maya.ph/docs/one-time-card-payment

Outlines the initial steps for integrating with Maya Vault, including authentication requirements using API keys and the necessity to design custom card input forms and response pages.

```APIDOC
Integration Setup:
- Authentication: Basic Authentication, requires API keys.
  - Refer to 'Generate API Keys for Online Payments' guide to obtain API keys.
- Required Pages: Design and host your own forms and response web pages.
  - 1. Create your Card Details form:
    - For customers to input payment information, adhering to Maya Vault's specifications.
    - Refer to 'Create Payment Token' for required card information.
    - PCI-DSS Warning: Do not store any card information (name, card number, expiry dates, CVV/CVC) on your application unless your platform is PCI-DSS certified.
  - 2. Create your Response pages:
    - Show appropriate web pages for every payment state.
    - Host these pages on your website.
    - Created URLs will be used in the redirectUrl object on the 'Create Customer Payment' transaction request.
```

--------------------------------

### Example JSON for Custom Fields in Maya Biller API Postman Collection

Source: https://developers.maya.ph/docs/biller-api-sandbox-integration-testing

Illustrates the JSON format for the CUSTOM_FIELDS variable in the Postman collection, showing how to structure additional fields for bill payment requests. It includes examples of various data types and field names.

```JSON
{ "FirstName": "Juan", "LastName": "Dela Cruz", "ContactNumber": "09170981234", "BillDate": "12/31/2023", "PaymentType": "STL" }
```

--------------------------------

### Maya Sandbox Credentials and Cards Guide

Source: https://developers.maya.ph/docs/shopify

Find information on obtaining sandbox credentials and test cards for development and testing purposes.

```APIDOC
https://developers.maya.ph/docs/sandbox-credentials-and-cards-guide
```

--------------------------------

### Disbursement API Endpoints and Related Services

Source: https://developers.maya.ph/docs/recurring-wallet-payments

This section outlines the various API endpoints available for the Maya Disbursement API, including quickstart guides, security session management, member operations, and detailed disbursement file processing, along with wallet inquiry.

```APIDOC
Disbursement API:
  Quickstart on Disbursement API
  Security API:
    /sessionspost
    /sessionsdelete
  Members API:
    /memberspost
    /members/{phoneNumber}get
  Disbursement API:
    /disbursementspost
    /disbursements/{disbursementId}get
    /disbursements/{disbursementId}post
    /disbursements/{disbursementId}/records-successget
    /disbursements/{disbursementId}/records-failedget
  Wallet API:
    /walletget
```

--------------------------------

### Guide to Validating Maya Bills Pay Endpoints via Postman

Source: https://developers.maya.ph/docs/biller-api-sandbox-integration-testing

This section outlines the step-by-step process for testing the biller's Validate endpoint using the provided Postman collection. It details how to modify transaction details and biller-specific fields, execute requests, and verify responses for successful integration. It emphasizes the importance of updating request parameters to match specific test cases.

```APIDOC
Postman Validate Endpoint Testing Steps:
1. Update 'transaction.amount.value' for the amount needed to facilitate your testing.
   - For validation test cases, add additional requests to the Postman collection and update accordingly.
2. Update 'biller.fields' value in your request to fit specific test cases, especially for biller-specific validation rules.
   - Refer to guidelines in the 'CUSTOM_FIELDS' section for updating additional fields.
3. Click on the 'SAVE' button to apply any changes made.
4. Click on the 'Send' button to execute the request.
5. Check the bottom part of the Postman window for the response body from Maya’s Biller API. Corresponding tests are provided per request to verify integration success.
```

--------------------------------

### Export Public GPG Key via Command Line

Source: https://developers.maya.ph/docs/gpg-guide

Use this command to export your public GPG key to a file named 'my-pubkey.asc'. Replace '<pub_id>' with the specific public key ID obtained after key generation.

```Shell
gpg --armor --export <pub_id> > my-pubkey.asc
```

--------------------------------

### Sample Response Body for Listing Invoices

Source: https://developers.maya.ph/docs/invoice-api-integration

Example JSON structure returned when retrieving a list of invoices, showing various invoice statuses and detailed information for each entry.

```JSON
{
    "totalCount": 3,
    "pageCount": 3,
    "invoices": [
        {
            "id": "53d77f1a-c867-487d-a6f8-fcd86030d59c",
            "invoiceNumber": "INV0001",
            "type": "SINGLE",
            "totalAmount": {
                "value": "100.00",
                "currency": "PHP",
                "details": null
            },
            "items": [],
            "requestReferenceNumber": "1551191039",
            "merchant": "sandbox-party-baec5035-5101-4b53-b03f-353b97e6731f",
            "createdAt": "2020-09-23T08:13:45.397Z",
            "updatedAt": "2020-09-23T08:13:45.397Z",
            "completedAt": null,
            "status": "PENDING",
            "redirectUrl": {
                "success": "https://www.merchantsite.com/success",
                "failure": "https://www.merchantsite.com/failure",
                "cancel": "https://www.merchantsite.com/cancel"
            },
            "metadata": {},
            "authorizationType": null
        },
        {
            "id": "1b5cfd3e-130a-459d-94d5-33ca3fba4a10",
            "invoiceNumber": "INV0001",
            "type": "SINGLE",
            "totalAmount": {
                "value": "100.00",
                "currency": "PHP",
                "details": null
            },
            "items": [],
            "requestReferenceNumber": "1551191039",
            "merchant": "sandbox-party-baec5035-5101-4b53-b03f-353b97e6731f",
            "createdAt": "2020-09-23T08:00:53.498Z",
            "updatedAt": "2020-09-23T08:10:34.257Z",
            "completedAt": "2020-09-23T08:10:34.256Z",
            "status": "COMPLETED",
            "redirectUrl": {
                "success": "https://www.merchantsite.com/success",
                "failure": "https://www.merchantsite.com/failure",
                "cancel": "https://www.merchantsite.com/cancel"
            },
            "metadata": {},
            "authorizationType": null
        },
        {
            "id": "286f3e86-12ea-4a66-966e-56e81b667136",
            "invoiceNumber": "INVOICE00002",
            "type": "OPEN",
            "totalAmount": {
                "value": null,
                "currency": "PHP",
                "details": null
            },
            "items": [],
            "requestReferenceNumber": "PGQEINVOICE",
            "merchant": "sandbox-party-baec5035-5101-4b53-b03f-353b97e6731f",
            "createdAt": "2020-09-23T07:00:32.380Z",
            "updatedAt": "2020-09-23T07:00:32.380Z",
            "completedAt": null,
            "status": "PENDING",
            "redirectUrl": null,
            "metadata": {},
            "authorizationType": null
        }
    ]
}
```

--------------------------------

### Maya Business Developer Resources

Source: https://developers.maya.ph/docs/invoice-faq

This section lists essential resources for developers working with Maya Business, including links to demo applications, guides, plugins, webhook documentation, and information on sandbox credentials for testing purposes.

```APIDOC
Demo Apps: https://developer-demos.maya.ph/?utm_source=J1010
GPG Guide: https://developers.maya.ph/docs/gpg-guide
Maya plugins: https://developers.maya.ph/docs/maya-plugins
Webhooks: https://developers.maya.ph/docs/receive-real-time-payment-information-using-webhooks
Sandbox credentials and cards: https://developers.maya.ph/docs/sandbox-credentials-and-cards-guide
```

--------------------------------

### Maya Remittance API Endpoints

Source: https://developers.maya.ph/docs/one-time-card-payment

Provides API endpoints for managing remittances to Maya accounts, including quick start guides, creating, executing, and checking remittance statuses. This section details the core operations for facilitating money transfers.

```APIDOC
Remittance API:
  POST /create-remittance
  PUT /execute-remittance
  GET /check-remittance
```

--------------------------------

### Maya Biller API Sandbox Postman Collection Variables Configuration

Source: https://developers.maya.ph/docs/biller-api-sandbox-integration-testing

Details the essential variables within the Maya Biller API SBX Postman collection that need to be configured. This includes unique biller identifiers, valid/invalid account numbers, custom fields, authorization headers, and callback URLs, crucial for successful sandbox integration testing.

```APIDOC
Variables:
  BILLER_SLUG:
    Description: Unique biller identifier on Maya’s end.
    Remarks: To be provided by Maya during the Sandbox Integration Testing.
  VALID_ACCOUNT_NUMBER:
    Description: Valid biller account number.
    Remarks: Input a valid account number that your service would accept during the validation step.
  CUSTOM_FIELDS:
    Description: Additional fields accepted for bill payment.
    Remarks: Should include Additional Fields that your service expects to receive from a bill payment request. This should be in JSON format. a. Field names should correspond to how Maya has configured the field on their end. b. For the drop-down type field, the value should be the mapped value of the option selected and not the placeholder. c. If no additional fields, input an empty body instead: {}. Example: { "FirstName": "Juan", "LastName": "Dela Cruz", "ContactNumber": "09170981234", "BillDate": "12/31/2023", "PaymentType": "STL" }
  INVALID_ACCOUNT_NUMBER:
    Description: Invalid biller account number.
    Remarks: Input an invalid account number that your service would not be able to accept during validation step.
  BILLER_API_ENDPOINT:
    Description: Designated endpoint for Maya’s Biller SBX environment.
    Remarks: Do not update.
  AUTHORIZATION_HEADER:
    Description: Authorization header value to be used for Callback.
    Remarks: Refer to Biller API Signature and Authorization for the computation of the authorization header. The Sandbox key will be provided during Integration Testing with Maya Bills Pay. NOTE: Configure the provided Sandbox secret key in the biller’s Sandbox environment services.
  BILLER_CALLBACK_URL:
    Description: Designated Callback API URL for Maya’s SBX environment.
    Remarks: Do not update.
  BILLER_CALLBACK_METHOD_URL:
    Description: This is Maya’s callback HTTP method.
    Remarks: Do not update.
```

--------------------------------

### Remittance API for Maya Accounts

Source: https://developers.maya.ph/docs/recurring-wallet-payments

This section provides a quick start guide and detailed documentation for the Remittance API, specifically for sending remittances to Maya accounts. It covers the process of creating, executing, and checking remittances, along with common remittance errors.

```APIDOC
Remittance API:
  Send Remittance to Maya Account only:
    Quick Start on Remittance
    Know before you code
    Create Remittancepost
    Execute Remittanceput
    Check Remittanceget
    Remittance Errors
```

--------------------------------

### Install Python Dependencies for ECR Simulator

Source: https://developers.maya.ph/docs/electronic-cash-register-simulator-tool

These commands install the necessary Python libraries, 'pythoncrc' and 'pyserial', required for the Electronic Cash Register Simulator Tool (remote-serial-pay.py) to function correctly. Ensure Python and pip are installed before running these commands.

```Python
pip install pythoncrc
```

```Python
pip install pyserial
```

--------------------------------

### Decrypting Encrypted Files with GPG Command Line

Source: https://developers.maya.ph/docs/gpg-guide

This command demonstrates how to decrypt an encrypted file, such as 'sampleEncryptedFile.asc', using the GPG utility. The output of the decryption process is redirected to a new plain text file, 'plain.txt'. Successful decryption requires that the user possesses the private key corresponding to the public key used for encryption.

```Shell
gpg --decrypt sampleEncryptedFile.asc > plain.txt
```

--------------------------------

### Example Authorization Header for Basic Authentication

Source: https://developers.maya.ph/docs/biller-api

This snippet demonstrates the complete format of the Authorization header required for authenticating requests to the Maya Biller API. It uses the 'Basic' scheme followed by the Base64 encoded API key.

```HTTP
Authorization: Basic cGstWjBPU3zMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=
```

--------------------------------

### Example Callback Authorization Header

Source: https://developers.maya.ph/docs/biller-api

This code snippet shows the HTTP Basic Access Authentication header expected when the Partner Biller sends the Send Posting Callback to Maya's Biller API. The `<credentials>` part is the Secret Key encoded in Base64.

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

--------------------------------

### Simulate Basic Sale Transaction with Debug Output

Source: https://developers.maya.ph/docs/electronic-cash-register-simulator-tool

This example demonstrates a basic sale transaction using the simulator in debug mode, showing the command, the structured JSON request and response payloads, and their raw hexadecimal representations. It illustrates the full communication flow for a sale.

```Python
$ python remote-serial-pay.py -t /dev/cu.usbmodem1423 -c SALE --amount 1000 --debug
```

```JSON
REQUEST: {
 "dataType": "trans",
 "data": {
 "amt": "1000",
 "cmd": "sale",
 "detail": "Y"
 }
}
```

```Hexadecimal
RAW REQUEST
0000004E7B226461746154797065223A20227472616E73222C202264617461223A207B22616D74223A2022313030302
22C2022636D64223A202273616C65222C202264657461696C223A202259227D7DCE4A
```

```Hexadecimal
RAW RESPONSE 000000147B226461746154797065223A2261636B227DFA22
```

```JSON
RESPONSE: {
 "dataType": "ack"
}
```

```Hexadecimal
RAW RESPONSE
000001E97B2264617461223A7B22616964223A224130303030303030303331303130222C22617070223A22564953412
054455354222C22617463223A2230304532222C2261757468436F6465223A22303239323233222C2262617463684E6
F223A22303030303032222C226361726454797065223A2256495341222C22656E7465724D6F6465223A2254222C226
E7465724D6F6465436F6465223A22303731222C226D65726368616E744964223A22454653313030303031313439222
C226E6F5369676E223A2259222C2270616E223A222A2A2A2A2A2A2A2A2A2A2A2A30303638222C227265666572656E6
3654E6F223A22383332353036303830313330222C22726573706F6E7365436F6465223A223030222C22726573706F6
E736554657874223A2254786E204163636570746564222C22737461747573223A2241222C22737474223A2259222C2
27465726D696E616C4964223A223132333435363738222C22747369223A2230303030222C22747672223A223030303
3030303030222C2274786E44617465223A223230313831313231222C2274786E4964223A22303030303230222C2274
786E54696D65223A2231343038222C2274786E54797065223A2273616C65222C22616D74223A2231303030227D2C2
226461746154797065223A227472616E73227D73C0
```

--------------------------------

### Post Endpoint Testing Scenarios

Source: https://developers.maya.ph/docs/biller-api-local-development-mock-testing

Outlines various testing scenarios for the Biller Post Endpoint, covering successful transactions and cases involving invalid Paymaya signatures. It provides guidance on inputting specific values to test different API behaviors and emphasizes the need for persisting requests and callback URLs.

```APIDOC
Scenario | Description
--- | ---
Successful Post Endpoint | Happy path testing for post endpoint. Input valid account number in **biller.accountNumber** If applicable, input valid/acceptable values under **biller.fields** and **transaction.amount.total.value** / **transaction.amount.base.value** / **transaction.amount.fee.value** to test all valid scenarios for your API. For this leg, your service should persist the request on your end as these are for posting already. We recommend persisting the callback URL included in the request as well as this is the endpoint to hit to inform Maya if the bill payment has been successfully posted.
Declined Post Endpoint - Invalid Paymaya Signature | Request to test if your API has computed the paymaya-signature header correctly.
```

--------------------------------

### Declined Callback: Missing Request-Reference-No Header

Source: https://developers.maya.ph/docs/biller-api-local-development-mock-testing

This scenario simulates a callback request where the 'Request-Reference-No' header and its corresponding value are entirely missing from the request, leading to a declined callback.

```APIDOC
Request Header: 'Request-Reference-No' (Missing)
```

--------------------------------

### Maya Webhook Endpoint Setup Requirements

Source: https://developers.maya.ph/docs/receive-real-time-payment-information-using-webhooks

Guidelines for setting up a secure and publicly accessible webhook endpoint for Maya. It must use SSL-secured (HTTPS) and accept JSON payloads via POST requests. Configuring SSL on port 443 is recommended to prevent network issues.

```APIDOC
Webhook Endpoint Requirements:
  Security: SSL-secured (https)
  Accessibility: Publicly accessible
  Method: POST requests
  Payload: JSON payloads
  Recommended SSL Port: 443
```

--------------------------------

### API Integration Essentials Overview

Source: https://developers.maya.ph/docs/quick-start-on-remittance

This section outlines the fundamental topics for integrating with the Maya API, covering API environments, different authentication methods (Basic and Bearer), and details on creating access tokens and handling OAuth 2.0 errors.

```APIDOC
API Integration Essentials:
  - API Environments
  - API Authentication Methods:
    - Basic Authentication
    - Bearer Authentication:
      - Create Access Token (POST /token)
      - OAuth 2.0 Authentication Errors
```

--------------------------------

### Disbursement API Endpoints

Source: https://developers.maya.ph/docs/save-a-card-only

Documentation for the Maya Disbursement API, including quickstart guides, security sessions, member management, and various disbursement file operations.

```APIDOC
Disbursement API:
  Quickstart on Disbursement API
  Security API:
    /sessionspost
    /sessionsdelete
  Members API:
    /memberspost
    /members/{phoneNumber}get
  Disbursement API:
    /disbursementspost
    /disbursements/{disbursementId}get
    /disbursements/{disbursementId}post
    /disbursements/{disbursementId}/records-successget
    /disbursements/{disbursementId}/records-failedget
  Wallet API:
    /walletget
```

--------------------------------

### API Integration Essentials Overview

Source: https://developers.maya.ph/docs/recurring-wallet-payments

A structured overview of the key topics for integrating with Maya APIs, detailing environments and various authentication methods.

```APIDOC
API Integration Essentials:
  - API Environments
  - API Authentication Methods:
    - Basic Authentication
    - Bearer Authentication:
      - Create Access Token (POST)
      - OAuth 2.0 Authentication Errors
```

--------------------------------

### Perform Settle Transaction with Python Script

Source: https://developers.maya.ph/docs/electronic-cash-register-simulator-tool

This example shows the full flow of a settle transaction initiated via a Python script. It includes the command-line execution, the structured JSON request, the raw hexadecimal representation of the request and response, and the parsed JSON response, illustrating the data exchange with the payment terminal.

```bash
$ python remote-serial-pay.py -t /dev/cu.usbmodem1423 --debug -c SETTLE
```

```json
{
 "dataType": "trans",
 "data": {
 "cmd": "settle"
 }
}
```

```hex
000000327B226461746154797065223A20227472616E73222C202264617461223A207B22636D64223A2022736574746
C65227D7DDF62
```

```hex
000000967B2264617461223A7B2262617463684E6F223A22303030303033222C22726573706F6E7365436F6465223A2
23030222C22726573706F6E736554657874223A2254786E204163636570746564222C22737461747573223A2241222C
2274786E54797065223A22736574746C65222C22626174636855706C6F6164223A224E227D2C2264617461547970652
3A227472616E73227DF56A
```

```json
{
 "data": {
 "batchNo": "000003",
 "responseCode": "00",
 "responseText": "Txn Accepted",
 "status": "A",
 "txnType": "settle",
 "batchUpload": "N"
 },
 "dataType": "trans"
}
```

--------------------------------

### Sample Webhook Endpoint Test HTTP Response

Source: https://developers.maya.ph/docs/receive-real-time-payment-information-using-webhooks

This snippet shows an example HTTP 200 OK response received after successfully testing a webhook endpoint, indicating it is reachable and functioning correctly. This output would typically be seen after executing a curl command or similar API client request.

```HTTP
HTTP/2 200
content-type: application/json; charset=utf-8
date: Mon, 14 Feb 2022 01:08:14 GMT
ngrok-agent-ips: 130.105.160.253
content-length: 18
```

--------------------------------

### Remittance API

Source: https://developers.maya.ph/docs/save-a-card-only

Documentation for the Remittance API, focusing on sending remittances to Maya accounts, including quick start guides, pre-coding information, and endpoints for creating, executing, and checking remittance status.

```APIDOC
Remittance API:
  Send Remittance to Maya Account only:
    Quick Start on Remittance
    Know before you code
    Create Remittancepost
    Execute Remittanceput
    Check Remittanceget
    Remittance Errors
```

--------------------------------

### API Reference: Create Webhook Endpoint

Source: https://developers.maya.ph/docs/receive-real-time-payment-information-using-webhooks

This entry refers to the API endpoint used for programmatically registering webhook URLs with Maya. It serves as an alternative to manual registration via the Maya Business Manager, allowing for automated setup of webhook subscriptions. Webhooks registered via this API will also be visible within the Maya Business Manager interface.

```APIDOC
Endpoint: /reference/createv1webhook-1
Method: POST (Implied by 'Create')
Description: Register a new webhook endpoint with Maya.
Parameters:
  - url: string (Required) - The publicly accessible HTTPS URL for your webhook endpoint.
  - events: array of strings (Required) - A list of event types to subscribe to.
Returns:
  - Success: 2xx status code indicating successful registration.
  - Error: Appropriate error status code for invalid input or server issues.
```

--------------------------------

### Maya Developer Demo Applications

Source: https://developers.maya.ph/docs/shopify

Explore sample applications demonstrating various Maya API integrations and functionalities.

```APIDOC
https://developer-demos.maya.ph/?utm_source=J1010
```

--------------------------------

### Check Remittance Status API Endpoint

Source: https://developers.maya.ph/docs/remittance-to-maya-wallet-technical-guide

This GET API endpoint allows checking the current status of a specific remittance transaction using its unique transaction reference number, which is acquired during the creation step.

```APIDOC
Endpoint: GET /remittances/v2/{transactionReferenceNumber}
Base URL: https://pg-sandbox.paymaya.com
Description: Retrieves the current status of a remittance transaction.
Path Parameters:
  - transactionReferenceNumber (string, required): The unique ID of the remittance transaction.
```

--------------------------------

### Remittance API Endpoints

Source: https://developers.maya.ph/docs/sandbox-credentials-and-cards-guide

Outlines the API endpoints for managing remittances to Maya accounts. This includes operations for creating, executing, and checking the status of remittances, along with quick start guides and error information.

```APIDOC
Remittance API:
  Send Remittance to Maya Account only:
    Quick Start on Remittance: /reference/quick-start-on-remittance
    Know before you code: /reference/remittance-know-before-you-code
    POST /create-remittance: /reference/create-remittance
    PUT /execute-remittance: /reference/execute-remittance
    GET /check-remittance: /reference/check-remittance
    Remittance Errors: /reference/remittance-errors
```

--------------------------------

### API Integration Essentials Overview

Source: https://developers.maya.ph/docs/receive-real-time-payment-information-using-webhooks

This snippet details the hierarchical structure of the Maya API integration documentation, covering environments and different authentication methods with their sub-topics.

```APIDOC
API Integration Essentials:
  - API Environments
  - API Authentication Methods:
    - Basic Authentication
    - Bearer Authentication:
      - Create Access Token (POST)
      - OAuth 2.0 Authentication Errors
```

--------------------------------

### Maya API Integration Essentials Overview

Source: https://developers.maya.ph/docs/one-time-card-payment

This section outlines the fundamental topics for integrating with Maya APIs, covering different environments, various authentication methods, and details on creating access tokens and handling OAuth 2.0 errors.

```APIDOC
API Integration Essentials:
  - API Environments
  - API Authentication Methods:
    - Basic Authentication
    - Bearer Authentication:
      - Create Access Token (post)
      - OAuth 2.0 Authentication Errors
```

--------------------------------

### Maya Mini App Partner APIs and Guidelines

Source: https://developers.maya.ph/docs/recurring-wallet-payments

This section provides documentation for partners developing Maya Mini Apps, covering functionalities like profile sharing, payments, and cash-in. It includes details on partner-hosted endpoints, Maya Mini Apps specific endpoints for token refresh, profile retrieval, payment creation and execution, and business rules for Mini App development.

```APIDOC
MAYA APP PARTNER:
  Maya Mini App:
    Profile Sharing
    Payments via Mini App
    Cash-in from a Mini App
    Partner-hosted Endpoints:
      Session URL API Contract
    Maya Mini Apps Endpoints:
      Refresh Maya Mini App Token
      Get Profile via Maya Mini App
      Create Maya Mini App Payment
      Execute Maya Mini App Payment
    Business Rules to Code for Maya Mini Apps
```

--------------------------------

### Maya Mini App Partner API Endpoints

Source: https://developers.maya.ph/docs/quick-start-on-remittance

Enables integration for Maya Mini App partners, covering functionalities like profile sharing, payments, and cash-in from a mini-app. It also includes endpoints for managing mini-app tokens and processing payments.

```APIDOC
MAYA APP PARTNER:
  Maya Mini App: /reference/maya-mini-app
    Profile Sharing: /reference/profile-sharing
    Payments via Mini App: /reference/payments-via-maya-mini-app
    Cash-in from a Mini App: https://paymaya-group.readme.io/reference/cash-in-from-a-mini-app
    Partner-hosted Endpoints:
      Session URL API Contract: /reference/session-url-api-contract
    Maya Mini Apps Endpoints:
      Refresh Maya Mini App Token: /reference/refresh-maya-mini-app-token
      Get Profile via Maya Mini App: /reference/get-profile-via-maya-mini-app
      Create Maya Mini App Payment: /reference/create-maya-mini-app-payment
      Execute Maya Mini App Payment: /reference/execute-maya-mini-app-payment
    Business Rules to Code for Maya Mini Apps: /reference/business-rules-to-code-for-maya-mini-apps
```

--------------------------------

### Maya Bills Pay Validate Endpoint Test Scenarios

Source: https://developers.maya.ph/docs/biller-api-sandbox-integration-testing

This section details various test scenarios for the Maya Bills Pay Validate endpoint, covering successful validations, invalid account numbers, and other custom validation errors. It provides guidance on modifying request parameters like 'biller.accountNumber', 'transaction.amount.value', and 'biller.fields' to simulate different outcomes and test specific validation logic. It also advises on returning descriptive error messages for customer display.

```APIDOC
Validate Endpoint Scenarios:

Scenario: Successful Validate Biller API
  Description: Happy path testing for validate endpoint.
  Inputs: Input valid/acceptable values under 'biller.fields' and 'transaction.amount.value' to facilitate a successful validation integration test between Maya and your API.

Scenario: Declined Validate Endpoint - Invalid Account Number
  Description: Request to test your invalid account number scenario.
  Inputs: Input an expected invalid account number in 'biller.accountNumber'.

Scenario: Declined Validate Endpoint - Other Validation Errors
  Description: Request to test any other validation error scenarios.
  Inputs: By default, the Postman collection has a negative value for 'transaction.amount.value' as this is an expected validation error for the amount field. If your API has an expected validation logic, update the appropriate fields as necessary.
    Examples:
    1. Minimum amount validation (e.g., Php 500): Input a value less than 500 under 'transaction.amount.value' to test your validation logic.
    2. Account number matching (e.g., First Name: Juan, Last Name: Dela Cruz): Update the values under 'biller.fields' to test your validation logic for this.
  Note: For such validation logic, we suggest returning a descriptive error message under 'result.message' in your validation response. This message will be directly displayed in the Maya App to the customer.
```

--------------------------------

### Maya Webhooks Documentation

Source: https://developers.maya.ph/docs/shopify

Learn how to receive real-time payment information using Maya webhooks for instant notifications.

```APIDOC
https://developers.maya.ph/docs/receive-real-time-payment-information-using-webhooks
```

--------------------------------

### Base64 Encoded API Key String Example

Source: https://developers.maya.ph/docs/biller-api

This snippet provides an example of a Base64 encoded API key string. This encoded value is crucial for inclusion in the Authorization header when making API requests using the Basic Authentication scheme.

```HTTP
cGstWjBPU3zMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=
```

--------------------------------

### Display Help Information (Python)

Source: https://developers.maya.ph/docs/electronic-cash-register-simulator-tool

This command shows all supported options and commands for the `remote-serial-pay.py` script. It provides a comprehensive list of functionalities available in the ECR simulator tool.

```Python
python remote-serial-pay.py --help
```

--------------------------------

### Perform Sale Transaction with Status Monitoring

Source: https://developers.maya.ph/docs/electronic-cash-register-simulator-tool

This snippet demonstrates how to initiate a sale transaction using a Python script, subscribe to status updates, and interpret the various JSON request and response messages, including the final transaction details. It shows the initial request, acknowledgment, intermediate status updates, and the final transaction response.

```Python
$ python remote-serial-pay.py -t /dev/cu.usbmodem1423 -c SALE --amount 1000 --debug --subscribe
```

```JSON
{
 "dataType": "trans",
 "data": {
 "amt": "1000",
 "subscribe": "Y",
 "cmd": "sale",
 "detail": "Y"
 }
}
```

```JSON
{
 "dataType": "ack"
}
```

```JSON
{
 "data": {
 "txnType": "sale",
 "status": "INPUT_CARD"
 },
 "dataType": "status"
}
```

```JSON
{
 "data": {
 "txnType": "sale",
 "status": "CLSS_PROC"
 },
 "dataType": "status"
}
```

```JSON
{
 "data": {
 "txnType": "sale",
 "status": "PRINT_RECEIPT"
 },
 "dataType": "status"
}
```

```JSON
{
 "data": {
 "aid": "A0000000031010",
 "app": "VISA TEST",
 "atc": "00E3",
 "authCode": "077655",
 "batchNo": "000003",
 "cardType": "VISA",
 "enterMode": "T",
 "enterModeCode": "071",
 "merchantId": "EFS100001149",
 "noSign": "Y",
 "pan": "************0068",
 "referenceNo": "832506174883",
 "responseCode": "00",
 "responseText": "Txn Accepted",
 "status": "A",
 "stt": "Y",
 "terminalId": "12345678",
 "tsi": "0000",
 "tvr": "0000000000",
 "txnDate": "20181121",
 "txnId": "000022",
 "txnTime": "1425",
 "txnType": "sale",
 "amt": "1000"
 },
 "dataType": "trans"
}
```

```JSON
{
 "dataType": "ACK"
}
```

--------------------------------

### `ACQ019`- Internal Server Error

Source: https://developers.maya.ph/docs/bills-payment-troubleshooting-guide

For the Biller API Sandbox environment, this is a catch-all error and may have varying causes.

```APIDOC
Error Code: ACQ019
Description: Internal Server Error
Products: Biller API
Troubleshooting Steps:
  - Biller Slug:
    - Check the value inputted under the BILLER_SLUG variable. This should match the provided biller slug onboarded by Maya.
    - Check the biller.slug value in your request body. The value should be the Postman variable placeholder: {{BILLER_SLUG}}
  - Custom Fields:
    - Check the value inputted under the CUSTOM_FIELDS variable. This should be a valid JSON format.
    - Check the biller.fields value in your request body. The value should be the Postman variable placeholder: {{CUSTOM_FIELDS}}
  - Transaction Date:
    - The transaction date for the request body is generated via Postman’s pre-request script. If there were any changes made in the Pre-request script, revert the changes made.
    - Check the transaction.date value in your request body. The value should be the Postman variable placeholder: {{BILLSPAY_TRANSACTION_DATE}}
  - Check if there were any general changes made on the request body. Request body should be a valid JSON format.
```

--------------------------------

### Get Wallet Balance

Source: https://developers.maya.ph/docs/disbursement-api-technical-details

Checks the client's wallet balance to ensure sufficient funds are available before initiating disbursements. This is an optional but recommended step.

```APIDOC
Endpoint: GET /wallet

Process:
1. Client to send a request via GET /wallet endpoint.
2. Disbursement API will return the client's account balance details.
```

--------------------------------

### Pay with Maya Wallet API

Source: https://developers.maya.ph/docs/sandbox-credentials-and-cards-guide

Documents the API for one-time payments using Maya Wallet, generating QRPh, linking wallets, and executing linked wallet payments.

```APIDOC
Pay with Maya:
  One-time Payment using Maya Wallet: /reference/one-time-payment-using-maya-wallet
  Generate a Maya QRPh: /reference/generate-a-maya-qrph
  Link a Maya Wallet: /reference/link-a-maya-wallet
  Pay using a Linked Maya Wallet: /reference/pay-using-a-linked-maya-wallet
  Endpoints:
    Create Single Payment: POST /v2/singlepayment (/reference/createv2singlepayment)
    Create Dynamic QR: POST /v2/dynamicqr (/reference/createdynamicqr)
    Create Wallet Link: POST /v2/walletlink (/reference/createv2walletlink)
    Get Wallet Link: GET /v2/walletlink/{id} (/reference/getv2walletlink)
    Delete Wallet Link: DELETE /v2/walletlink/{id} (/reference/deletev2walletlink)
    Execute Wallet Link Payment: POST /v2/walletlink/execute (/reference/executev2walletlink)
```

--------------------------------

### Sample Response Body for Cancel Invoice

Source: https://developers.maya.ph/docs/invoice-api-integration

Example JSON structure returned after successfully cancelling an invoice, showing the updated status as 'CANCELLED' and other relevant invoice details.

```JSON
{
    "id": "53d77f1a-c867-487d-a6f8-fcd86030d59c",
    "invoiceNumber": "INV0001",
    "type": "SINGLE",
    "totalAmount": {
        "value": "100.00",
        "currency": "PHP",
        "details": null
    },
    "items": [],
    "requestReferenceNumber": "1551191039",
    "merchant": "sandbox-party-baec5035-5101-4b53-b03f-353b97e6731f",
    "createdAt": "2020-09-23T08:13:45.397Z",
    "updatedAt": "2020-09-23T08:21:35.612Z",
    "completedAt": null,
    "status": "CANCELLED",
    "redirectUrl": {
        "success": "https://www.merchantsite.com/success",
        "failure": "https://www.merchantsite.com/failure",
        "cancel": "https://www.merchantsite.com/cancel"
    },
    "metadata": {},
    "authorizationType": null,
    "payments": []
}
```

--------------------------------

### Cash-in to Maya Wallet API Endpoints

Source: https://developers.maya.ph/docs/quick-start-on-remittance

Offers various methods for users to cash-in funds to their Maya Wallet, including via Maya Login, unique codes, or mini-apps. This section also details associated business rules, daily transaction reconciliation, and error handling.

```APIDOC
Cash-in to Maya Wallet:
  Cash-in via Maya Login:
    User Authorization for Cash-in via Maya Login: /reference/user-authorization-for-cash-in-via-maya-login
    Create Cash-in using User Access Token: /reference/create-cash-in-using-user-access-token
  Cash-in via Code: /reference/cash-in-via-code
  Cash-in from a Mini App: /reference/cash-in-from-a-mini-app
  Endpoints:
    POST /initiate: /reference/initiateusingpost
    GET /retrieve: /reference/retrieveusingget_1
    PUT /execute: /reference/executeusingput
  Business Rules to Code for Cash-in to Maya Wallet: /reference/business-rules-to-code-for-cash-in
  Daily Transaction Reconciliation: /reference/daily-transaction-reconciliation
  Cash-in to Maya Wallet Errors: /reference/money-movement-errors
```

--------------------------------

### Maya Mini App Integration Endpoints Summary

Source: https://developers.maya.ph/docs/maya-mini-apps-technical-guide

This table summarizes the key endpoints developed by the Mini App and the data exchanged with Maya during the session initiation process. It highlights the inputs and outputs for both the Session URL and the Landing Page.

```APIDOC
Your URL/Endpoints | Data you'll Receive | Data you'll Return
--- | --- | ---
Session URL | accessToken refreshToken expiresAt | sessionId
Landing Page | sessionId |
```

--------------------------------

### Get Successful Disbursement Records

Source: https://developers.maya.ph/docs/disbursement-api-technical-details

Retrieves a list of successful disbursement records for a specific disbursement ID. This endpoint provides details on transactions that have been successfully processed.

```APIDOC
Endpoint: GET /disbursements/{disburementId}/records-success

Process:
1. Client to send request via the GET /disbursements/{disbursementId}/records-success endpoint.
2. Disbursement API will return a list of disbursement records with status TRANSFER_ACCEPTED.
```

--------------------------------

### Remittance Transfer State Definitions

Source: https://developers.maya.ph/docs/remittance-to-maya-wallet-technical-guide

Provides a comprehensive overview of the lifecycle states for a remittance transfer, detailing the meaning and implications of each state from creation to completion or failure.

```APIDOC
State: CREATED
  Description: The initial state of the remittance transfer intent upon successful creation.
State: PROCESSING
  Description: This state means that Maya has initiated the processing of the remittance transfer upon calling the execute remittance transfer endpoint. It indicates that the process is currently underway and has not yet been completed.
State: APPROVED
  Description: A state when the remittance transfer passed all the validations and was processed successfully.
State: DECLINED
  Description: A remittance transaction will transition to this state when it does not pass the validation checks and/or encounters processing errors. For the list of error codes, please refer to: Remittance Errors.
State: EXPIRED
  Description: A status for a remittance transaction that is not executed within one (1) hour after its creation.
```

--------------------------------

### Construct HTTP Basic Authentication Header

Source: https://developers.maya.ph/docs/online-payments-quick-start-guide-maya-manager-1

Demonstrates the final construction of the HTTP Authorization header for API requests. It combines the 'Basic' scheme, a space, and the Base64 encoded API key string to authenticate with Maya APIs.

```text
Authorization: Basic cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=
```

--------------------------------

### ECR Status R: Card Not Read Properly JSON Example

Source: https://developers.maya.ph/docs/ecr-error-response-codes

Illustrates a sample JSON response for an ECR transaction aborted due to the card not being read properly.

```json
{
  "data": {
    "responseText": "Transaction Aborted",
    "status": "R",
    "txnType": "sale"
  },
  "dataType": "trans"
}
```

--------------------------------

### Security API Endpoints

Source: https://developers.maya.ph/docs/receive-real-time-payment-information-using-webhooks

Provides endpoints for managing user sessions, including initiation and termination.

```APIDOC
/sessionspost
/sessionsdelete
```

--------------------------------

### Get Disbursement File Status

Source: https://developers.maya.ph/docs/disbursement-api-technical-details

Retrieves the current status of a previously submitted disbursement file using its unique disbursementId. This allows clients to track the progress of their disbursement.

```APIDOC
Endpoint: GET /disbursements/{disbursementId}

Process:
1. Using the disbursementId, Client can get the disbursement file status via the GET /disbursements/{disbursementId} endpoint.
2. Disbursement API will return the status for the disbursement file.

Disbursement File Statuses:
Status | Description
--- | ---
Creating… | Started the creation of disbursement records in Disbursement API
Ready to Disburse | Done creating disbursement record and is ready for execution
Disbursing… | Execution of disbursement has started
Completed | All records on the file were disbursed successfully
Completed (with errors) | Some records succeeded; some have failed.
Failed | No records on the file were disbursed successfully
```

--------------------------------

### Troubleshoot Webhook Notification Failures

Source: https://developers.maya.ph/docs/woocommerce-plugin-troubleshooting-guide

Steps to diagnose and fix issues with webhook notifications not being triggered or received, including checking setup, logs, and network security.

```English
1. Review our [Basic Troubleshooting Steps](/docs/woocommerce-plugin-troubleshooting-guide#basic-troubleshooting-steps).
2. Do another transaction and take note of the **order number** (in WooCommerce dashboard) and **reference number** (in Maya Manager).
3. Check [Webhooks Setup](/docs/woocommerce-plugin-troubleshooting-guide#review-webhook-setup).
4. Check logs if relevant webhooks are sent (**Maya Manager logs**) and received ([WooCommerce plugin logs](/docs/woocommerce-plugin-troubleshooting-guide#retrieving-woocommerce-logs)).
5. **Retrigger Webhook** in Maya Manager.
6. Check **network security setup** of merchant site, turn-off firewall, contact hosting provider (troubleshoot for possible hosting issues).
7. Do another transaction and check if there is still an error / if something still does not work.
8. If you need further help, check [this](/docs/woocommerce-plugin-troubleshooting-guide#if-you-need-further-help).
```