Changelog​

Orders​

Bug Fixes​

• Fix: Resolved an issue where, in some cases, the payment page was incorrectly generated when creating an order with "dataEntryMode": "redirect". This caused the user to be unable to redirect to the provider's page because the Pay button was not clickable.

• Fix: Resolved a bug where the Retrieve Order Details could accept payoutNumber as orderNumber. This endpoint now only accepts orderNumber. If payoutNumber is provided as orderNumber, an error will be returned:

  {
    "message": "Not found order number some_number in shop with id: some_shop_id",
    "code": 404
  }
  

Payouts​

Bug Fixes​

• Fix: Resolved an issue where the response from the Retrieve Required Payout Fields endpoint sometimes included an empty recipient property. The response now adheres to the documentation.
• Fix: Corrected a problem where creating a payout would fail due to missing mandatory fields. Payouts are now created correctly.

Changes expected in the next release​

• Feature: There will be an option for manual resending of the order/payout status callback. In the merchant account dashboard, within the order/payout details window, a button Send order status by API will be added. Clicking this button will resend the order or payout status callback. The callback will be sent to the addresses specified in the callback settings, and if webhookUrl was specified during the order/payout creation, both callbacks (settings and webhookUrl) will be sent.

• As we mentioned in the previous release note, the new payout endpoint Retrieve Required Payout Fields is currently available but is returning placeholder responses instead of actual data. We are working on finalizing this feature, and it will be fully functional and provide accurate data in the next release.

Changelog​

General​

• Fix: Addressed an issue where payouts could be created without specifying all required fields. Now, such requests will return an error indicating the missing fields.
• Update: Added a new TransferType value virtual_account. See TransferType doc.

Orders​

• Update: A new parameter transferType has been added to the paymentSettings object in the Create Order endpoint. This allows specifying the type of bank transfer when instrumentType is bank_transfer.

Payouts​

• Update: A new optional parameter region has been added to the payout object in the Create Payout Request endpoint. Specifying the region is mandatory for payouts through certain providers.
• Update: A new object sender, with a structure similar to recipient, has been added to the Create Payout Request endpoint. This is required by some providers to include sender information for the payout.
• Update: A new parameter transferType has been added to the bankTransferData objects within both recipient and sender in the Create Payout Request endpoint. This allows specifying the type of bank transfer when instrumentType is bank_transfer.

Changes expected in the next release​

The structure of the response for the future POST endpoint Retrieve Required Payout Fields has been radically updated, which will eventually replace the current GET Retrieve Required Payout Fields endpoint.

Changelog​

New Features​

Retrieve Payment Methods Endpoint Update​

In the Retrieve Payment Methods Endpoint, a new mandatory parameter dataEntryMode has been added to the response. This parameter specifies the methods for customer data entry to process payments.

The dataEntryMode value obtained from the response of the Retrieve Payment Methods Endpoint is now used in the paymentSettings object of the Create Order Endpoint.

Changelog​

New Features​

Payout Creation Endpoint Update​

In the Payout Creation Endpoint, a new optional parameter webhookUrl has been added. This parameter allows you to specify a webhook URL for receiving notifications about payout status changes for this specific payout.

Payment Status and Webhook Response Update​

A new parameter providerPaymentId has been added to the response of the Retrieve Order Details and order Callback. This parameter is the identifier for the specific payment assigned by the payment provider.

Payment Settings Update​

A new optional parameter dataEntryMode has been added to the paymentSettings object of the Create Order endpoint. This parameter specifies the methods for customer data entry to process payments:

• redirect: The customer enters payment information on the provider's (acquirer's) page via redirect.
• h2h (host2host): The customer enters payment information on our payment page.
• qr: The customer scans a QR code and enters information on the aggregator's side.

Improvements​

Order Time Limit Increase​

The default order time limit has been increased from 15 minutes to 24 hours (+1 day from the time of order creation). Change the timeLimit only if you understand the implications.

Synchronization of Order Status Endpoint and Webhook Responses​

As promised in the previous release, we have synchronized the responses of the order status endpoint and webhook, making their responses identical.

Changelog​

New Features​

Order Creation endpoint update​

In the order creation endpoint, a new optional parameter webhookUrl has been added to the paymentSettings object. This parameter allows specifying an individual webhook for order status changes for each order. webhookUrl is of type string and is validated as a URL, so it must begin with https://.

If webhookUrl is specified when creating an order, notifications about the order status change will be sent to this URL and will not be sent to the general webhook URL set for the shop.

The new parameter is highlighted in the code below:

{
  "shopId": 1234,
  "order": {
    "orderNumber": "56573FDFVFDBWF",
    "cost": {
      "amount": "56.99",
      "currency": "PHP"
    }
  },
  "customer": {
    "customerId": "56656",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "James",
    "phone": "79221110500",
    "email": "john.doe@mymail.com"
  },
  "paymentSettings": {
    "instrumentType": "wallet",
    "providerCode": "connectpay",
    "acquirerCode": "gcash",
    "entryMode": null,
    "autoCapture": true,
    "timeLimit": "2024-02-03T10:51:49.086Z",
    "redirectUrls": {
      "success": "https://example.com/success",
      "failure": "https://example.com/failure"
    },
    "webhookUrl": "https://example.com/webhook"
  },
  "paymentPageDesign": {
    "alias": "default",
    "format": "redirect"
  }
}

Improvements​

Customer ID uniqueness update​

The logic for the customerId parameter in the order creation endpoint has been modified. The customerId can now be unique either within a shop or across the entire company/merchant. The existing logic remains unchanged for current merchants, meaning customerId uniqueness remains within the shop by default. This update simply adds the option to change this setting via the technical support. To determine the setting for your shop, check the admin panel of your merchant account under the settings menu in the field 'External customer ID unique for'.

Changes expected in the next release​

Payouts​

Addition of a new endpoint and future deprecation of an existing endpoint​

In future versions, the endpoint /payouts/fields/{providerCode}/{instrumentType}/ Retrieve Required Payout Fields will be declared deprecated. It will be replaced by a new endpoint, /api/v1/payouts/fields Retrieve Required Payout Fields, which is currently under development. The response structures of these endpoints will be identical, but the new endpoint will support a significantly larger number of parameters in the request, allowing it to support a wider range of providers.

The /payouts/fields/{providerCode}/{instrumentType}/ Retrieve Required Payout Fields endpoint will gradually be discontinued. We will make a separate announcement to inform you when it is officially deprecated.

Addition of a new parameter in the payout creation endpoint​

A new optional parameter, transferType, will be added to the Payout Creation Request. The new transferType parameter will be mandatory when creating a payout with instrumentType == bank_transfer.

The new parameter that will be added is highlighted in this request example:

{
  "shopId": 2,
  "payout": {
    "cost": {
      "amount": "100.50",
      "currency": "PHP"
    },
    "payoutNumber": "43242332"
  },
  "purpose": "string",
  "providerCode": "connectpay",
  "acquirerCode": "gcash",
  "instrumentType": "bank_transfer",
  "transferType": "bank_wire",
  "customer": {
    "customerId": "56656",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "James",
    "phone": "79221110500",
    "email": "john.doe@mymail.com"
  }
}

Orders​

The changes mentioned in the previous changelog (14.05.2024) regarding the webhook with breaking changes will not be made in this release but will be implemented in the next release on 11.06.2024. For now, the webhook remains unchanged.

Lines highlighted will be removed from the webhook in the next release.

{
  "id": 77,
  "number": "7_1706275173",
  "status": "in_progress",
  "cost": {
    "amount": "56.99",
    "currency": "USD"
  },
  "timeLimit": {
    "date": "2024-01-27 07:45:51.000000",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "orderCreatedAt": {
    "date": "2024-01-26 13:19:33.222170",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "orderPaidAt": {
    "date": "2024-01-26 13:19:33.222170",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "captureNeeded": false,
  "payments": [
    {
      "id": "79",
      "type": "payment",
      "parentPaymentId": "83",
      "cost": {
        "amount": "56.99",
        "currency": "USD"
      },
      "acquirerCode": "fyst",
      "paymentMethod": "card",
      "paymentDetails": {
        "type": "card",
        "authCode": "auth94753457343",
        "rrn": "rrn583743856734",
        "maskedCardNumber": "123456******1234"
      }
    }
  ],
  "customer": {
    "id": 13,
    "name": "John",
    "middleName": "James",
    "surname": "Doe",
    "phone": "79221110500",
    "email": "john.doe@mymail.com"
  },
  "data": {
    "shopId": 123,
    "orderNumber": "56573FDFVFDBWF",
    "orderStatus": "in_progress",
    "cost": {
      "amount": "56.99",
      "currency": "USD"
    },
    "timeLimit": "2023-08-29T15:34:56+03:00",
    "orderCreatedAt": "2023-08-29T15:34:56+03:00",
    "orderPaidAt": "2023-08-29T15:34:56+03:00",
    "autoCapture": true,
    "payments": [
      {
        "paymentId": "79",
        "paymentType": "payment",
        "parentPayment": "83",
        "cost": {
          "amount": "56.99",
          "currency": "USD"
        },
        "acquirer": {
          "code": "fyst"
        },
        "instrumentType": "card",
        "paymentDetails": {
          "authCode": "auth94753457343",
          "maskedCardNumber": "123456******1234",
          "rrn": "rrn583743856734"
        }
      }
    ],
    "customer": {
      "customerId": "56656",
      "firstName": "John",
      "lastName": "Doe",
      "middleName": "James",
      "phone": "79221110500",
      "email": "john.doe@mymail.com"
    }
  }
}

Changelog​

Changes expected in the next release​

In the order creation endpoint, a new optional parameter webhookUrl will be added to the paymentSettings object. This parameter allows specifying an individual webhook for order status changes for each order. webhookUrl is of type string and is validated as a URL, so it must begin with https://.

If webhookUrl is specified when creating an order, notifications about the order status change will be sent to this URL and will not be sent to the general webhook URL set for the shop.

The new parameter is highlighted in the code below:

{
  "shopId": 1234,
  "order": {
    "orderNumber": "56573FDFVFDBWF",
    "cost": {
      "amount": "56.99",
      "currency": "PHP"
    }
  },
  "customer": {
    "customerId": "56656",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "James",
    "phone": "79221110500",
    "email": "john.doe@mymail.com"
  },
  "paymentSettings": {
    "instrumentType": "wallet",
    "providerCode": "connectpay",
    "acquirerCode": "gcash",
    "entryMode": null,
    "autoCapture": true,
    "timeLimit": "2024-02-03T10:51:49.086Z",
    "redirectUrls": {
      "success": "https://example.com/success",
      "failure": "https://example.com/failure"
    },
    "webhookUrl": "string"
  },
  "paymentPageDesign": {
    "alias": "default",
    "format": "redirect"
  }
}

The changes mentioned in the previous changelog (30.04.2024) regarding the webhook with breaking changes will not be made in this release but will be implemented in the next release on 28.05.2024. For now, the webhook remains unchanged.

Lines highlighted will be removed from the webhook in the next release.

{
  "id": 77,
  "number": "7_1706275173",
  "status": "in_progress",
  "cost": {
    "amount": "56.99",
    "currency": "USD"
  },
  "timeLimit": {
    "date": "2024-01-27 07:45:51.000000",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "orderCreatedAt": {
    "date": "2024-01-26 13:19:33.222170",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "orderPaidAt": {
    "date": "2024-01-26 13:19:33.222170",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "captureNeeded": false,
  "payments": [
    {
      "id": "79",
      "type": "payment",
      "parentPaymentId": "83",
      "cost": {
        "amount": "56.99",
        "currency": "USD"
      },
      "acquirerCode": "fyst",
      "paymentMethod": "card",
      "paymentDetails": {
        "type": "card",
        "authCode": "auth94753457343",
        "rrn": "rrn583743856734",
        "maskedCardNumber": "123456******1234"
      }
    }
  ],
  "customer": {
    "id": 13,
    "name": "John",
    "middleName": "James",
    "surname": "Doe",
    "phone": "79221110500",
    "email": "john.doe@mymail.com"
  },
  "data": {
    "shopId": 123,
    "orderNumber": "56573FDFVFDBWF",
    "orderStatus": "in_progress",
    "cost": {
      "amount": "56.99",
      "currency": "USD"
    },
    "timeLimit": "2023-08-29T15:34:56+03:00",
    "orderCreatedAt": "2023-08-29T15:34:56+03:00",
    "orderPaidAt": "2023-08-29T15:34:56+03:00",
    "autoCapture": true,
    "payments": [
      {
        "paymentId": "79",
        "paymentType": "payment",
        "parentPayment": "83",
        "cost": {
          "amount": "56.99",
          "currency": "USD"
        },
        "acquirer": {
          "code": "fyst"
        },
        "instrumentType": "card",
        "paymentDetails": {
          "authCode": "auth94753457343",
          "maskedCardNumber": "123456******1234",
          "rrn": "rrn583743856734"
        }
      }
    ],
    "customer": {
      "customerId": "56656",
      "firstName": "John",
      "lastName": "Doe",
      "middleName": "James",
      "phone": "79221110500",
      "email": "john.doe@mymail.com"
    }
  }
}

Changelog​

Updates​

General​

• Update: The Developers -> Shop section has been updated to include the ability to specify separate webhook URLs for orders (payment acceptance) and for payouts.
• New feature: Added a new callback for payouts, enhancing the integration options for payout functionalities.

Orders​

• Update: A new parameter acquirerCode has been added to the paymentSettings object of the Create Order endpoint.
• Update: New possible parameters transferType and purpose have been added to the payments array in the paymentDetails object of the Retrieve Order Details endpoint. These are used for instrumentType=bank_transfer.
• Update: A new mandatory parameter acquirerCode has been added to the response of the Retrieve Payment Methods endpoint.

Payouts​

• Update: A mandatory payoutOptions object has been added to the response of the Retrieve Required Payout Fields endpoint.
• Update: A new string walletName has been added to the RecipientWalletData object in the response of the Retrieve Required Payout Fields endpoint.
• Update: New values have been added to the transferTypes enum in the Retrieve Payout Methods endpoint.
• Update: A new mandatory parameter acquirerCode has been added to the response of the Retrieve Payout Methods endpoint.
• Update: New parameters entryMode, allowedCards, and isDefault have been added to the response of the Retrieve Payout Methods endpoint.
• Update: A new mandatory parameter acquirerCode has been added to the request of the Create Payout Request endpoint.

Changes expected in the next release​

Lines highlighted will be removed from the webhook in the next release.

{
  "id": 77,
  "number": "7_1706275173",
  "status": "in_progress",
  "cost": {
    "amount": "56.99",
    "currency": "USD"
  },
  "timeLimit": {
    "date": "2024-01-27 07:45:51.000000",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "orderCreatedAt": {
    "date": "2024-01-26 13:19:33.222170",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "orderPaidAt": {
    "date": "2024-01-26 13:19:33.222170",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "captureNeeded": false,
  "payments": [
    {
      "id": "79",
      "type": "payment",
      "parentPaymentId": "83",
      "cost": {
        "amount": "56.99",
        "currency": "USD"
      },
      "acquirerCode": "fyst",
      "paymentMethod": "card",
      "paymentDetails": {
        "type": "card",
        "authCode": "auth94753457343",
        "rrn": "rrn583743856734",
        "maskedCardNumber": "123456******1234"
      }
    }
  ],
  "customer": {
    "id": 13,
    "name": "John",
    "middleName": "James",
    "surname": "Doe",
    "phone": "79221110500",
    "email": "john.doe@mymail.com"
  },
  "data": {
    "shopId": 123,
    "orderNumber": "56573FDFVFDBWF",
    "orderStatus": "in_progress",
    "cost": {
      "amount": "56.99",
      "currency": "USD"
    },
    "timeLimit": "2023-08-29T15:34:56+03:00",
    "orderCreatedAt": "2023-08-29T15:34:56+03:00",
    "orderPaidAt": "2023-08-29T15:34:56+03:00",
    "autoCapture": true,
    "payments": [
      {
        "paymentId": "79",
        "paymentType": "payment",
        "parentPayment": "83",
        "cost": {
          "amount": "56.99",
          "currency": "USD"
        },
        "acquirer": {
          "code": "fyst"
        },
        "instrumentType": "card",
        "paymentDetails": {
          "authCode": "auth94753457343",
          "maskedCardNumber": "123456******1234",
          "rrn": "rrn583743856734"
        }
      }
    ],
    "customer": {
      "customerId": "56656",
      "firstName": "John",
      "lastName": "Doe",
      "middleName": "James",
      "phone": "79221110500",
      "email": "john.doe@mymail.com"
    }
  }
}

Changelog​

Bug Fixes​

• Corrected in Retrieve Order Details and Callback: Fixed an issue where the autoCapture parameter was incorrectly displayed for one-stage payments. It now correctly reflects true for one-stage payments where funds are automatically captured, aligning with the documentation.

New Features​

• Added to Create Order Request: A new object redirectUrls has been introduced, allowing specification of URLs for redirecting users after successful or unsuccessful payment transactions. This ensures a better user experience by clearly guiding the customers following payment processing.

Changelog​

New Features​

• Added: Payouts are now fully supported with four new refactored endpoints for handling payout processes.
  • Create Payout Request: New endpoint to initiate a new payout request.
  • Retrieve Payout Status: New endpoint to retrieve the current status of a specific payout operation for a shop.
  • Retrieve Payout Methods: New GET endpoint to retrieve the list of payout methods available for a given shop, identified by its {shopId}. This endpoint provides an unfiltered list of all payout methods applicable to the shop.
  • Retrieve Required Payout Fields: New endpoint to retrieve necessary data fields for initiating a payout through a specific provider.

Updates​

• Update: The Retrieve Order Details endpoint has been updated to include shopId and orderNumber parameters.
• Update: The format of the Callback has been synchronized with the response of the Retrieve Order Details. This change was made while preserving backward compatibility.
  Note: In the next release, backward compatibility will be removed, and the Callback will only return the data object, making its format fully identical to the Retrieve Order Details endpoint.

Changelog​

New Features​

• Added: New endpoint Retrieve Payment Methods to retrieve payment methods.

  • Details: The new endpoint allows merchants to fetch all available payment methods for a specified shop via its shopId. The information obtained serves to fill the paymentSettings object with necessary data during the order creation process.

• Added: Payouts are now supported with three new endpoints for handling payout processes.

  • Create Payout Request: New endpoint to initiate a new payout request.
    • Details: Merchants can now initiate payout requests.
  • Retrieve Payout Status: New endpoint to retrieve the current status of a specific payout operation for a shop.
    • Details: This endpoint provides the ability to check the status of a payout operation.
  • Retrieve Required Payout Fields: New endpoint to retrieve necessary data fields for initiating a payout through a specific provider.
    • Details: Merchants can retrieve the required fields for the recipient object necessary for initiating a payout, specific to a provider and instrument type.

Updates​

• Update: In the Create Order endpoint, the orderNumber parameter is now mandatory for creating an order.
  • Details: The orderNumber serves as a unique identifier for the order, which you need to generate. It must be specific to the shopId and unique for each order within that shopId.