### Get Payment Instructions

Source: https://convera.readme.io/docs/option-3-agentpartner-model-overview

Retrieves payment instructions for a logged item.

```APIDOC
## Get Payment Instructions

### Description
Provides details on how to pay Convera for a logged item.

### Parameters
#### Request Body
- **GPFI Deal Reference** (string) - Required
```

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

### Get Languages

Source: https://convera.readme.io/docs/option-3-agentpartner-model-overview

Retrieves a list of supported languages for documentation and notifications.

```APIDOC
## Get Languages

### Description
Provides a list of languages that the Payment Instructions PDF and notifications are available in.
```

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

### GET /languages

Source: https://convera.readme.io/docs/option-2-customer-model-2-overview

Retrieves a list of languages available for Payment Instructions PDF and notifications.

```APIDOC
## GET /languages

### Description
To provide a list of languages that the Payment Instructions PDF, and notifications, are available in.

### Method
GET

### Endpoint
/languages
```

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

### Sample XML Response from External Service

Source: https://convera.readme.io/docs/data-definition

An example of a successful response received from a mock external service, indicating a status update.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<statusUpdateResponse>
		<responseCode>200</responseCode>
		<responseMessage>Updated Successfully</responseMessage>
		<transactionId>100000002895</transactionId>
	</statusUpdateResponse>
```

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

### Get Payment Instructions API

Source: https://convera.readme.io/docs/option-2-customer-model-2-overview

Retrieves payment instructions for a logged item. This provides the necessary details for the payer to make the payment to Convera.

```APIDOC
## Get Payment Instructions

### Description
To provide details of how to pay Convera for a logged item.

### Method
GET

### Endpoint
/payment-instructions/{orderIdentifier}

### Parameters
#### Path Parameters
- **orderIdentifier** (string) - Required - The identifier of the logged order for which to retrieve payment instructions.

### Response
#### Success Response (200)
- **paymentInstructions** (object) - An object containing detailed payment instructions.
```

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

### FAB Bank Directory Plus Fields

Source: https://convera.readme.io/docs/find-a-bank-resource-bank-directory-plus-file

Definitions and examples of SWIFT Bank Directory Plus fields used in the Find-a-Bank (FAB) response.

```APIDOC
## FAB Bank Directory Plus Fields

### Description
This section provides definitions for the SWIFT Bank Directory Plus fields. The fields returned in the Find-a-Bank (FAB) response may differ from these names to align with the API resource model.

### Fields

#### MODIFICATION FLAG
- **Description**: Modification flag in delta files. A - addition, M - modification, D - deletion in full files.
- **Always Present?**: Yes
- **Format**: `string(1)`

#### RECORD KEY
- **Description**: Unique key of the record in the file.
- **Always Present?**: Yes
- **Format**: `string(12)`

#### OFFICE TYPE
- **Description**: Type of office. HO - Head Office, -DB - Domestic branch or department, -SB - Sub-domestic branch, -FB - Foreign branch, -SF - Sub-foreign branch, UC - Unclassified.
- **Always Present?**: Yes
- **Format**: `string(2)`

#### PARENT OFFICE KEY
- **Description**: Indicates the RECORD KEY of the closest entity upwards in the hierarchy. Ex. "HO" RECORD KEY if the entity is "DB", or the "FB" RECORD KEY if "SF".
- **Always Present?**: Yes
- **Format**: `string(12)`

#### HEAD OFFICE KEY
- **Description**: Indicates the RECORD KEY of the "HO - Head Office" in the entities hierarchy.
- **Always Present?**: Yes
- **Format**: `string(12)`

#### LEGAL TYPE
- **Description**: Indicates the status of the entity in the legal hierarchy. L - Legal entity, B - Business entity, U - Unknown.
- **Always Present?**: Yes
- **Format**: `string(1)`

#### LEGAL PARENT KEY
- **Description**: Legal hierarchy included in Entity Plus product. This data is not maintained in the Bank Directory Plus, and is often the same as the record key.
- **Always Present?**: Yes
- **Format**: `string(12)`

#### GROUP TYPE
- **Description**: Type of entity identifying group: Parent, Member. This data comes from the SWIFT back office. Parent BIC is the BIC at the top of the SWIFT traffic hierarchy. This can be different than the legal ultimate parent that is available in Entity Plus.
- **Always Present?**: No
- **Format**: `string(6)`

#### GROUP PARENT KEY
- **Description**: Record key of parent entity. Identifies set of entity records belonging to that group. Groups BICs and National ID records that belong to the same parent BIC.
- **Always Present?**: No
- **Format**: `string(12)`

#### INSTITUTION STATUS
- **Description**: Indicates license status of the institution, if any: BANK - Universal Bank, COOP - Cooperative Bank, CBMA - Central Bank/Monetary Authority, ASSM - Asset Manager, CORP - Corporates, CRUN - Credit Union.
- **Always Present?**: Yes
- **Format**: `string(4)`
```

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

### Quote Field Definitions

Source: https://convera.readme.io/docs/quote-fields-1

A reference guide for the fields associated with a Quote.

```APIDOC
## Quote Field Definitions

### Description
This section defines the fields associated with a Quote object.

### Fields
- **Field Definitions** - The following fields are available for Quote objects. Please refer to the specific API implementation for data types and requirements.
```

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

### VOP Validation Webhook Responses

Source: https://convera.readme.io/docs/eu-vop-webhooks

Examples of the vop.validationCompleted webhook payload for different match scenarios.

```json
{
  "id": "61171e0f-e3f1-40b3-a010-222c53990be4",
  "eventType": "vop.validationCompleted",
  "createdOnUTC": "2025-09-22T10:42:51Z",
  "summary": "VOP validation has been completed.",
  "resource": {
    "paymentId": "UMXXOhqsItSejejNIPJqO8a3e4CZhuRF",
    "accountName": "Sophie Weber",
    "accountNumber": "DE28503399002244668800",
    "matchScore": "1",
    "matchType": "MTCH",
    "matchDescription": "Strong Match",
    "disclaimer": null,
    "validationMessage": "The payee name and payment identifier which you have provided match exactly, please requote to proceed.",
    "partnerName": "MPCPL3",
    "customerName": "MOSESFRMPCPL3",
    "batchId": "LpqdAWxpGQmdaqmUrKGC9SnzMRU2L06Q",
    "validationCompletedOnUtc": "2025-09-22T10:42:51.5905159Z"
  }
}
```

```json
{
  "id": "87c2462a-7488-46e3-a557-99584b67350b",
  "eventType": "vop.validationCompleted",
  "createdOnUTC": "2025-09-22T10:49:27Z",
  "summary": "VOP validation has been completed.",
  "resource": {
    "paymentId": "ZTYjfccWArkUN8tjOJdH33mKe7SLAMx2",
    "accountName": "S Weber",
    "accountNumber": "DE28503399002244668800",
    "matchScore": "0.5",
    "matchType": "CMTC",
    "matchDescription": "Close Match",
    "disclaimer": "If you go ahead with this request, the name will remain the same. Please note that authorizing the credit transfer may lead to transferring the funds to a payment account not held by the beneficiary which you have indicated.If you chose to ignore this notification and proceed, Convera shall not be held liable for the execution of the credit transfer to an unintended payee and you may not be entitled to receive a refund for the amount transferred.",
    "validationMessage": "The provided Payee Name and account number of the beneficiary almost match. The name of the beneficiary associated with the provided bank account number is: Sophie Weber. This gives you a chance to double-check and confirm that your money is going to the right person or business. You can cancel the payment, update the details and send again with a different payment ID. Or you can requote to proceed.",
    "partnerName": "MPCPL3",
    "customerName": "MOSESFRMPCPL3",
    "batchId": "rmcZcOcU0JDeQ2o0WvQ610xHXKCMkFRS",
    "validationCompletedOnUtc": "2025-09-22T10:49:26.5184657Z"
  }
}
```

```json
{
  "id": "245b3d2b-eabe-4087-9bc1-3cf8e0dde17a",
  "eventType": "vop.validationCompleted",
  "createdOnUTC": "2025-09-22T10:56:37Z",
  "summary": "VOP validation has been completed.",
  "resource": {
    "paymentId": "VL8Yd2GN9BE6oACXSbXmmbjPXEDMG9x2",
    "accountName": "Sofy",
    "accountNumber": "DE28503399002244668800",
    "matchScore": "0",
    "matchType": "NMTC",
    "matchDescription": "No Match",
    "disclaimer": "Only proceed with the payment if you are certain the payee details are correct. By choosing to proceed with this payment this might affect your rights to a refund and our liability as your payment service provider.",
    "validationMessage": "Warning: The provided Payee Name and account number of the beneficiary do not match. Please note that authorizing the payment may lead to transferring the funds to an account not held by the intended beneficiary. You can cancel the payment, update the details and send again with a different payment ID. Or you can requote to proceed.",
    "partnerName": "MPCPL3",
    "customerName": "MOSESFRMPCPL3",
    "batchId": "7Kpd3F3ZbwpsYQrH76bqMd49Xw3oLEO9",
    "validationCompletedOnUtc": "2025-09-22T10:56:37.217398Z"
  }
}
```

```json
{
  "id": "132b4192-b772-44ff-a672-d6f3a4fd415f",
  "eventType": "vop.validationCompleted",
  "createdOnUTC": "2025-09-22T11:02:02Z",
  "summary": "VOP validation has been completed.",
  "resource": {
    "paymentId": "yd6QUY7fGVBKV9vzRA0gPW3Tt4I1kkha",
    "accountName": "Sophie Weber",
    "accountNumber": "DE28503399002244668899",
    "matchScore": "0",
    "matchType": "NOAP",
    "matchDescription": "Verification Not Possible",
    "disclaimer": "If you choose to ignore this notification and proceed, Convera shall not be held liable for the execution of the payment to an unintended payee and you may not be entitled to receive a refund for the amount transferred."
  }
}
```

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

### Requote API Response

Source: https://convera.readme.io/docs/quote-for-eu-vop-check-payments

Example of a successful quote creation response following a VOP validation.

```json
{
    "id": "46EEF8AF-AE1E-4370-8035-80F3CA5B5CE6"
```

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

### Beneficiary Validation API Responses

Source: https://convera.readme.io/docs/quote-for-eu-vop-check-payments

Examples of JSON responses from the VOP API indicating different match statuses for beneficiary details.

```json
{
    "expirationIntervalInSec": 0,
    "validationOfBeneficiary": [
        {
            "paymentId": "UMXXOhqsItSejejNIPJqO8a3e4CZhuRF",
            "name": "Sophie Weber",
            "iban": "DE28503399002244668800",
            "matchScore": "1",
            "matchType": "MTCH",
            "matchDescription": "Strong Match",
            "validationMessage": "The payee name and payment identifier which you have provided match exactly, please requote to proceed."
        }
    ]
}
```

```json
{
    "expirationIntervalInSec": 0,
    "validationOfBeneficiary": [
        {
            "paymentId": "VL8Yd2GN9BE6oACXSbXmmbjPXEDMG9x2",
            "name": "Sofy",
            "iban": "DE28503399002244668800",
            "matchScore": "0",
            "matchType": "NMTC",
            "matchDescription": "No Match",
            "validationMessage": "Warning: The provided Payee Name and account number of the beneficiary do not match. Please note that authorizing the payment may lead to transferring the funds to an account not held by the intended beneficiary. You can cancel the payment, update the details and send again with a different payment ID. Or you can requote to proceed.",
            "disclaimer": "Only proceed with the payment if you are certain the payee details are correct. By choosing to proceed with this payment this might affect your rights to a refund and our liability as your payment service provider."
        }
    ]
}
```

```json
{
    "expirationIntervalInSec": 0,
    "validationOfBeneficiary": [
        {
            "paymentId": "yd6QUY7fGVBKV9vzRA0gPW3Tt4I1kkha",
            "name": "Sophie Weber",
            "iban": "DE28503399002244668899",
            "matchScore": "0",
            "matchType": "NOAP",
            "matchDescription": "Verification Not Possible",
            "validationMessage": "The verification check cannot be completed. It cannot be confirmed that the provided Payee Name matches the account number. We cannot verify these details, if you are unsure, you have the correct information, please cancel the payment and once verified resend with a new payment ID. Or you can proceed at your own risk, by requoting.",
            "disclaimer": "If you choose to ignore this notification and proceed, Convera shall not be held liable for the execution of the payment to an unintended payee and you may not be entitled to receive a refund for the amount transferred."
        }
    ]
}
```

```json
{
    "expirationIntervalInSec": 0,
    "validationOfBeneficiary": [
        {
            "paymentId": "M5yeYjvzz6F9JHG5P49F9jXN7pX9g2O7",
            "name": "Otto Larsen",
            "iban": "DE15801640509362882000",
            "matchScore": "0",
            "matchType": "NTVL",
            "matchDescription": "Not Validated",
            "validationMessage": "The verification check cannot be completed at this time. We cannot verify these details, if you are unsure, you have the correct information, please cancel the payment and once verified resend with a new payment ID. Or you can proceed at your own risk, by requoting.",
            "disclaimer": "Only proceed with the payment if you are certain the payee details are correct. By choosing to proceed with this payment, you understand and agree that you are doing so at your own risk. Convera shall not be held liable for the execution of the credit transfer to an unintended payee and you may not be entitled to receive a refund for the amount transferred."
        }
    ]
}
```

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

### Get Payment Types

Source: https://convera.readme.io/docs/option-3-agentpartner-model-overview

Retrieves a list of payment types available for a specific country and client.

```APIDOC
## Get Payment Types

### Description
Provides a list of payment types for the payer to choose from, specific to the country of receipt and client capabilities.

### Parameters
#### Request Body
- **GPFI Client Id** (string) - Required
- **Remitter Country** (string) - Required
- **Payment Currency** (string) - Required
```

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

### Get Settlement Currencies

Source: https://convera.readme.io/docs/option-3-agentpartner-model-overview

Retrieves a list of settlement currencies available for the client.

```APIDOC
## Get Settlement Currencies

### Description
Provides a list of settlement currencies associated with the client's declared currencies available in 'Holding'.

### Parameters
#### Request Body
- **GPFI Client Id** (string) - Required
```

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

### Get Payment Currencies

Source: https://convera.readme.io/docs/option-3-agentpartner-model-overview

Retrieves a list of payment currencies available for a specific country and client.

```APIDOC
## Get Payment Currencies

### Description
Provides a list of payment currencies for the payer to choose from, specific to the country of receipt and client capabilities.

### Parameters
#### Request Body
- **GPFI Client Id** (string) - Required
- **Remitter Country** (string) - Required
- **Payment Currency** (string) - Required
```

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

### Beneficiary Validation Response

Source: https://convera.readme.io/docs/quote-for-eu-vop-check-payments

Example response containing validationOfBeneficiary details such as match type and score.

```json
{
    "expirationIntervalInSec": 0,
    "validationOfBeneficiary": [
        {
            "paymentId": "jP54rrHcB7a1siUpbKIfiYH0fMd9UHIx",
            "name": "S Weber",
            "iban": "DE28503399002244668800",
            "matchScore": "0.5",
            "matchType": "CMTC",
            "matchDescription": "Close Match"
```

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

### settlement.statusChanged JSON Payload

Source: https://convera.readme.io/docs/webhook-overview

Example structure of the settlement.statusChanged event payload. Use this to parse incoming webhook notifications for settlement updates.

```json
{
    "id": "ff09d885-3624-4d1f-9ed0-79d02984e6c8",
    "eventType": "settlement.statusChanged",
    "createdOnUTC": "2022-01-21T05:55:24Z",
    "summary": "A Settlement status has been changed.",
    "resource": {
        "id": "123456789",
        "customerId": "customer_01",
        "batchId": "batch_01",
        "createdOn": "12/9/2021 11:14:53 AM",
        "lastUpdatedOn": "12/9/2021 11:14:53 AM",
        "settlementCurrency": "GBP",
        "lastdatereceived": "12/9/2021 11:14:53 AM",
        "amountreceived": "1.1",
        "amountdue": "5.58",
        "amount": "6.68"
    }
}
```

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

### Ping Event Payload

Source: https://convera.readme.io/docs/webhook-overview

Example payload for a ping event, used for health checks and connection testing.

```json
{
  "id": "2fa38c3d-11fc-4f58-8aee-b01965cbf789",
  "eventType": "ping",
  "createdOnUTC": "2022-01-07T16:15:17Z",
  "summary": "Ping request was successful."
}
```

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

### Sample Input for Creating an Order

Source: https://convera.readme.io/docs/orders-resource

This sample JSON demonstrates the input format required for creating a new order, specifying settlement details and optional approver information.

```json
{
    "settlements": [
        {
            "settlementCurrency": "CAD",
            "settlementMethod": "Wire"
        }
    ],
    "approverName": "Optional approver",
    "authorizationCode": "Optional authorization"
}
```

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

### GET /reconciliation-report

Source: https://convera.readme.io/docs/option-2-customer-model-2-overview

Retrieves details of items updated for settlement/disbursement.

```APIDOC
## GET /reconciliation-report

### Description
To provide details of items having been updated for settlement / disbursement from ‘Holding’ for the client.

### Method
GET

### Endpoint
/reconciliation-report

### Parameters
#### Query Parameters
- **GPFI Client Identifier** (string) - Required
- **Date Range** (string) - Required
```

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

### GET /disbursed-items

Source: https://convera.readme.io/docs/option-2-customer-model-2-overview

Retrieves settlement/disbursement details at an item level.

```APIDOC
## GET /disbursed-items

### Description
To provide details of settlement / disbursements from ‘Holding’ for the client at an item level.

### Method
GET

### Endpoint
/disbursed-items

### Parameters
#### Query Parameters
- **GPFI Client Identifier** (string) - Required
- **Date Range** (string) - Required
```

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

### Import Embedded Tracking Solution SDK

Source: https://convera.readme.io/docs/embedded-payment-tracking-overview

Load the JavaScript SDK from the CDN URL. Convera recommends this over saving the JavaScript locally.

```javascript
<script src="https://sandbox-uat.spm.convera.com/static/js/main.js"></script>
```

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

### GET /disbursed-orders-report

Source: https://convera.readme.io/docs/option-2-customer-model-2-overview

Retrieves settlement/disbursement details at a disbursement level.

```APIDOC
## GET /disbursed-orders-report

### Description
To provide details of settlement / disbursements from ‘Holding’ for the client at a disbursement level.

### Method
GET

### Endpoint
/disbursed-orders-report

### Parameters
#### Query Parameters
- **Date Range** (string) - Required
```

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

### GET /order-status

Source: https://convera.readme.io/docs/option-2-customer-model-2-overview

Retrieves the latest status of a specific order.

```APIDOC
## GET /order-status

### Description
To provide details on latest status of the order.

### Method
GET

### Endpoint
/order-status

### Parameters
#### Query Parameters
- **GPFI Client Identifier** (string) - Required
- **GPFI Order Identifier** (string) - Required
```

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

### Implement Custom Event Listener

Source: https://convera.readme.io/docs/integration-overview

Use this script to initialize the payment component and attach an event listener to handle incoming payment events.

```javascript
<script>
    var DATA_INPUT = '<?xml+version="1.0"+encoding="UTF-8"+standalone="yes"?>\
<paymentInformation>\
	<clientReference>TES90</clientReference>\
	<clientId>1000452465</clientId>\
  <merchantId>0c420d9cae0f4f6f85aaddbde33e8063</merchantId>\
  <merchantSecret>K7jkj12hjhkjbdd</merchantSecret>\
	<buyerCanEdit>true</buyerCanEdit>\
  <returnUrl>https://www.google.com</returnUrl>\
  <buyer>\
		<id>STUD9001</id>\
		<firstName>James</firstName>\
		<lastName>Bond</lastName>\
		<address>Brooklyn St</address>\
		<city>London</city>\
		<state>London</state>\
		<zip>21121</zip>\
		<country>GBR</country>\
		<email>james.bond@gmail.com</email>\
		<customField>90000</customField>\
	</buyer>\
	<service>\
		<id>100000026090</id>\
		<amount>100.90</amount>\
	</service>\
		<service>\
		<id>100000026091</id>\
		<amount>10.99</amount>\
	</service>\
</paymentInformation>';

  let converaPayment = document.createElement('convera-payment');
  converaPayment.setAttribute('data-seller-info', DATA_INPUT );
  converaPayment.setAttribute('data-payment-events-enabled', "true");
 
  // Name of the Custom event - converaEvent  
  converaPayment.addEventListener('converaEvent', (event) => {
      console.log('event received:', event); //  event JSON object
   });

</script>
```

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

### Get Order Status

Source: https://convera.readme.io/docs/option-3-agentpartner-model-overview

Retrieves the latest status of an order.

```APIDOC
## Get Order Status

### Description
Provides details on the latest status of the order.

### Parameters
#### Request Body
- **GPFI Client Identifier** (string) - Required
- **GPFI Order Identifier** (string) - Required
```

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

### Initiate Embedded Tracking Script

Source: https://convera.readme.io/docs/embedded-payment-tracking-overview

Initiate the script by passing required fields like clientId, merchantId, and merchantSecret. These merchant-specific credentials are generated by Convera.

```json
{
  "paymentInformation": {
    "clientId": 1000452465,
    "merchantId": "0c420d9cae0f4f6f85aaddbde33e8063",
    "merchantSecret": "K7jkj12hjhkjbdd"
  }
}
```

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

### Create a New Payment Batch

Source: https://convera.readme.io/docs/getting-started

This cURL command demonstrates how to create a new batch for collecting payments. Batches can hold multiple currencies, with a soft limit of 5,000 payments for optimal performance.

```cURL
# PUT /customers/:id/batches/:id
$ curl https://masspay.api.convera.com/MassPayments/customers/customer_01/batches/batch_01
```

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

### Get Disbursed Orders Report

Source: https://convera.readme.io/docs/option-3-agentpartner-model-overview

Retrieves a report of disbursements at the order level.

```APIDOC
## Get Disbursed Orders Report

### Description
Provides details of settlement/disbursements from 'Holding' for the client at a disbursement level.

### Parameters
#### Request Body
- **Date Range** (string) - Required
```

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

### JavaScript for Embedded Payment with Theme

Source: https://convera.readme.io/docs/integration-overview

Integrate the payment solution by passing payment information and theme configuration as data attributes to the convera-payment element. Ensure XML data is properly escaped.

```javascript
<script>
    var DATA_INPUT = '<?xml+version="1.0"+encoding="UTF-8"+standalone="yes"?>\n<paymentInformation>\n\t<clientReference>TES90</clientReference>\n\t<clientId>1000452465</clientId>\n  <merchantId>0c420d9cae0f4f6f85aaddbde33e8063</merchantId>\n  <merchantSecret>K7jkj12hjhkjbdd</merchantSecret>\t\n  <buyerCanEdit>true</buyerCanEdit>\n  <returnUrl>https://www.google.com</returnUrl>\n\t<buyer>\n\t\t<id>STUD9001</id>\n\t\t<firstName>James</firstName>\n\t\t<lastName>Bond</lastName>\n\t\t<address>Brooklyn St</address>\n\t\t<city>London</city>\n\t\t<state>London</state>\n\t\t<zip>21121</zip>\n\t\t<country>GBR</country>\n\t\t<email>james.bond@gmail.com</email>\n\t\t<customField>90000</customField>\n\t</buyer>\n\t<service>\n\t\t<id>100000026090</id>\n\t\t<amount>100.90</amount>\n\t</service>\n\t\t<service>\n\t\t<id>100000026091</id>\n\t\t<amount>10.99</amount>\n\t</service>\n</paymentInformation>';
    let themeInfo=JSON.stringify({"primaryColor":"#ff595e","secondaryColor":"#6a4c93","accentColors":["#ff595e","#6a4c93","#2133AF"],"warningColor":"#6a4c93","primaryButtonColor":"\"Jersey 10\", sans-serif","fontName":"\"Jersey 10\", sans-serif","fontUrl":"https://fonts.googleapis.com/css2?family=Jersey+10&display=swap"});
    let sellerInfo = `<convera-payment data-seller-info='${DATA_INPUT}' data-theme='${themeInfo}'></convera-payment>`
    $('#sellerInput').html(sellerInfo);
</script>
```

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

### XML Wrapper for Non-XML Responses

Source: https://convera.readme.io/docs/data-definition

Demonstrates how non-XML responses are encapsulated within a standard XML document using `<data>` tags.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<nonXmlResponse>
		<data>response data</data>
	</nonXmlResponse>
```

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

### Get Reconciliation Report

Source: https://convera.readme.io/docs/option-1-customer-model-1-overview

Provides details of items updated for settlement/disbursement from 'Holding' for the client.

```APIDOC
## GET /reconciliation-report

### Description
To provide details of items having been updated for settlement / disbursement from ‘Holding’ for the client.

### Method
GET

### Endpoint
/reconciliation-report

### Query Parameters
- **GPFI Client Identifier** (string) - Required - The unique identifier for the client.
- **Date Range** (string) - Required - The period for which to retrieve the reconciliation report.
```

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

### POST /real-time-callback

Source: https://convera.readme.io/docs/data-definition

Describes the technical interface for the Real Time Call Back service, including transport protocols and expected response formats.

```APIDOC
## POST /real-time-callback

### Description
This endpoint represents the callback service invoked by the GP2.0 platform. It requires HTTPS/TLS 1.2 and uses HTTP Basic Authentication.

### Method
POST

### Request Body
- **Content-Type** (string) - Required - application/xml

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **errorCode** (string) - Optional - Error code if the operation failed.
- **retry** (boolean) - Optional - Indicates if a retry is required.
- **narrative** (string) - Optional - Descriptive message regarding the status.

#### Response Example
<?xml version="1.0" encoding="UTF-8"?>
<realTimeCallbackResponse xmlns="http://bp.globalpay.wu.com/realtime">
  <success>true</success>
</realTimeCallbackResponse>
```

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

### Initiate Convera Payment Script with XML Data

Source: https://convera.readme.io/docs/integration-overview

Initiate the Embedded Payment Solution script by passing merchant ID, secret, and payment details in XML format to the custom UI element. Ensure the merchantID and merchantSecret are generated by Convera.

```javascript
var DATA_INPUT = '<?xml+version="1.0"+encoding="UTF-8"+standalone="yes"?>\\
<paymentInformation>\\
    <clientReference>Ref1</clientReference>\\
    <clientReference1>Ref2</clientReference1>\\
    <clientReference2>Ref3</clientReference2>\\
    <clientId>1000452465</clientId>\\
    <merchantId>0c420d9cae0f4f6f85aaddbde33e8063</merchantId>\\
    <merchantSecret>K7jkj12hjhkjbdd</merchantSecret>\\
    <buyerCanEdit>true</buyerCanEdit>\\    \\
    <returnUrl>https://www.google.com</returnUrl>\\      <buyer>\\        <id>STUD9001</id>\\
        <firstName>James</firstName>\\
        <lastName>Bond</lastName>\\
        <address>Brooklyn St</address>\\
        <city>London</city>\\
        <state>London</state>\\
        <zip>21121</zip>\\
        <country>GBR</country>\\
        <email>james.bond@gmail.com</email>\\
        <customField>90000</customField>\\\\
		</buyer>\\\\
		<service>\\        <id>100000026090</id>\\
        <amount>100.90</amount>\\\\
		</service>\\\\
				<service>\\        <id>100000026091</id>\\
        <amount>10.99</amount>\\\\
		</service>\\\\
</paymentInformation>'\\
    let sellerInfo = `<convera-payment data-seller-info='${DATA_INPUT}'></convera-payment>`\\
    $('#sellerInput').html(sellerInfo);\\
</script>
```

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

### Get Disbursed Items

Source: https://convera.readme.io/docs/option-1-customer-model-1-overview

Retrieves settlement and disbursement details from 'Holding' for the client at an item level.

```APIDOC
## GET /disbursed-items

### Description
To provide details of settlement / disbursements from ‘Holding’ for the client at an item level.

### Method
GET

### Endpoint
/disbursed-items

### Query Parameters
- **GPFI Client Identifier** (string) - Required - The unique identifier for the client.
- **Date Range** (string) - Required - The period for which to retrieve disbursement items.
```

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

### Buyer Object Structure

Source: https://convera.readme.io/docs/integration-overview

Details the fields available for the Buyer Object, used to pass buyer-specific information.

```APIDOC
## Buyer Object

### Description
Data on the user the payment is being made by or on behalf of (ex. Student).

### Fields
- **id** (String) - Optional - Buyer ID generated by merchant
- **firstName** (String) - Optional - First name of the buyer
- **lastName** (String) - Optional - Last name of the buyer
- **placeOfBirth** (String) - Optional - Place of birth of the buyer
- **nationality** (String) - Optional - Nationality of the buyer
- **email** (String) - Optional - Email of the buyer
- **dateOfBirth** (String) - Optional - Date of Birth of the buyer
- **address** (String) - Optional - Address of the buyer
- **city** (String) - Optional - City of the buyer
- **state** (String) - Optional - State of the buyer
- **country** (String) - Optional - Country of the buyer
- **customField** (String) - Optional - Custom Field defined by merchant
```

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

### Log Expected Receivable

Source: https://convera.readme.io/docs/option-3-agentpartner-model-overview

Creates an outstanding receivable for Agent model usage.

```APIDOC
## Log Expected Receivable

### Description
Creates an outstanding receivable for Agent model usage, independent of other order logging endpoints.

### Parameters
#### Request Body
- **GPFI Client ID** (string) - Required
- **Foreign Order ID** (string) - Required
- **Item resource** (object) - Required
```

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

### Validate Payment Response

Source: https://convera.readme.io/docs/quote-for-eu-vop-check-payments

Successful response from the get payment details API confirming the transaction status.

```json
{
    "totalPages": 1,
    "currentPage": 1,
    "totalCount": 1,
    "hasPrevious": false,
    "hasNext": false,
    "payments": [
        {
            "id": "5L7VxslQVmuqDagt9AqCPnBPYq1SG6bS",
            "batchId": "4A4FVIuTip4TWIMMdvXaVhlghcnZ9gkG",
            "status": "Created",
            "partnerReference": "partner",
            "paymentReference": "aa",
            "createdOn": "2025-09-24T13:21:28Z",
            "lastUpdatedOn": "2025-09-24T13:21:28Z"
        }
    ]
}
```

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

### Add a Payment to a Batch

Source: https://convera.readme.io/docs/getting-started

Submit a payment to an existing batch using this cURL command. Each payment must have a unique ID within the partner account. Refer to the API documentation for payment payload structure and required fields.

```cURL
# PUT /customers/:id/batches/:id/payments
$ curl https://masspay.api.convera.com/MassPayments/customers/customer_01/batches/batch_01/payments
```

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

### POST /validate-beneficiary

Source: https://convera.readme.io/docs/validation-of-beneficiary-eu

Validates beneficiary name and IBAN against Euro Zone banking records.

```APIDOC
## POST /validate-beneficiary

### Description
Validates beneficiary details for Euro Zone beneficiaries to ensure accurate payment processing.

### Method
POST

### Request Body
- **currencyCode** (string) - Required - The currency code (e.g., EUR)
- **beneficiary** (object) - Required - Beneficiary details
  - **name** (string) - Required - Name of the beneficiary
  - **countryCode** (string) - Required - Country code (e.g., BE)
- **bankAccount** (object) - Required - Bank account details
  - **iban** (string) - Required - The IBAN of the beneficiary

### Request Example
{
  "currencyCode": "EUR",
  "beneficiary": {
    "name": "Marc Janssen",
    "countryCode": "BE"
  },
  "bankAccount": {
    "iban": "BE84504754703434"
  }
}

### Response
#### Success Response (200)
- **beneficiary** (object) - The validation result object
  - **name** (string) - Beneficiary name
  - **iban** (string) - Beneficiary IBAN
  - **matchScore** (string) - Numerical score of the match
  - **matchType** (string) - Type of match (e.g., MTCH, CMTC, NMTC, NTVL)
  - **matchDescription** (string) - Description of the match result
  - **validationMessage** (string) - Detailed validation feedback
  - **disclaimer** (string) - Optional disclaimer regarding payment risk

#### Response Example
{
  "beneficiary": {
    "name": "Marc Janssen",
    "iban": "BE84504754703434",
    "matchScore": "1",
    "matchType": "MTCH",
    "matchDescription": "Strong Match",
    "validationMessage": "The payee name and payment identifier which you have provided match exactly."
  }
}
```

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

### Payment Information Object Structure

Source: https://convera.readme.io/docs/integration-overview

Details the fields available for the Payment Information object, including required and optional parameters.

```APIDOC
## Payment Information Object

### Description
Data specific to the client configuration.

### Fields
- **clientReference** (String) - Optional - This is the unique transaction reference ID that the merchant generates in their system
- **clientReference1** (String) - Optional - This is the unique transaction reference ID that the merchant generates in their system
- **clientReference2** (String) - Optional - This is the unique transaction reference ID that the merchant generates in their system
- **clientId** (String) - Required - This is a unique ID that identifies a merchant in Convera's ecosystem
- **merchantId** (String) - Required - This is a unique ID that is generated by Convera
- **merchantSecret** (String) - Required - This is a unique secret that is generated by Convera
- **buyerCanEdit** (Boolean) - Optional - Buyer ability to edit populated data points related to buyer or service information
- **returnUrl** (String) - Optional - This is a URL that the buyer can be redirected to after completing their payment
- **buyer** (Object) - Optional - Information passed in payload related to the buyer. See **Buyer Object** for details.
- **service** (Object) - Required - Information on service the buyer is paying for. See **Service Object** for details.
```

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

### Custom Event Listener Integration

Source: https://convera.readme.io/docs/integration-overview

This snippet demonstrates how to add a custom event listener to the convera-payment element. It includes setting up the payment information and attaching an event listener for 'converaEvent'.

```APIDOC
## Custom Event Listener Integration

### Description
This code demonstrates how to integrate a custom event listener into your system when using the embedded payment solution. It shows how to pass payment information and how to listen for custom events triggered by the payment process.

### Method
JavaScript (Client-side)

### Endpoint
N/A (Client-side integration)

### Parameters
#### Request Body (Implicitly set via attributes)
- **data-seller-info** (string) - Required - XML string containing payment and buyer information.
- **data-payment-events-enabled** (string) - Required - Set to "true" to enable payment events.

### Request Example
```javascript
<script>
    var DATA_INPUT = '<?xml+version="1.0"+encoding="UTF-8"+standalone="yes"?>\n<paymentInformation>\n\t<clientReference>TES90</clientReference>\n\t<clientId>1000452465</clientId>\n  <merchantId>0c420d9cae0f4f6f85aaddbde33e8063</merchantId>\n  <merchantSecret>K7jkj12hjhkjbdd</merchantSecret>\n\t<buyerCanEdit>true</buyerCanEdit>\n  <returnUrl>https://www.google.com</returnUrl>\n  <buyer>\n\t\t<id>STUD9001</id>\n\t\t<firstName>James</firstName>\n\t\t<lastName>Bond</lastName>\n\t\t<address>Brooklyn St</address>\n\t\t<city>London</city>\n\t\t<state>London</state>\n\t\t<zip>21121</zip>\n\t\t<country>GBR</country>\n\t\t<email>james.bond@gmail.com</email>\n\t\t<customField>90000</customField>\n\t</buyer>\n\t<service>\n\t\t<id>100000026090</id>\n\t\t<amount>100.90</amount>\n\t</service>\n\t\t<service>\n\t\t<id>100000026091</id>\n\t\t<amount>10.99</amount>\n\t</service>\n</paymentInformation>';

  let converaPayment = document.createElement('convera-payment');
  converaPayment.setAttribute('data-seller-info', DATA_INPUT );
  converaPayment.setAttribute('data-payment-events-enabled', "true");
 
  // Name of the Custom event - converaEvent  
  converaPayment.addEventListener('converaEvent', (event) => {
      console.log('event received:', event); //  event JSON object
   });

</script>
```

### Response
#### Event Object Structure

- **source** (string) - Indicates the source of the event (e.g., "EPS_CONVERA").
- **timestamp** (string) - The time the event occurred.
- **paymentMethod** (string) - The payment method used (optional, may be null).
- **clientRef** (string) - The client reference associated with the payment.
- **paymentStatus** (string) - The status of the payment ("PROCESSING", "SUCCESS", or "FAILURE").
- **eventType** (string) - The type of event triggered ("REDIRECT", "SESSION_EXPIRY", or "ORDER_COMPLETE").

#### Response Example
```json
{
  "source": "EPS_CONVERA",
  "timestamp": "2023-10-27T10:00:00Z",
  "paymentMethod": "Credit Card",
  "clientRef": "TES90",
  "paymentStatus": "SUCCESS",
  "eventType": "ORDER_COMPLETE"
}
```
```

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

### Service Object Structure

Source: https://convera.readme.io/docs/integration-overview

Details the fields available for the Service Object, used to describe the fee being paid.

```APIDOC
## Service Object

### Description
Data on the fee the buyer is paying for (ex. Type of fee and amount).

### Fields
- **id** (String) - Required - This is a unique ID shared by Convera to detail item being paid for
- **amount** (Decimal) - Required - This is the amount that the buyer is paying (rounded to two decimal places)
```

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

### JavaScript for Embedded Payment with Locale

Source: https://convera.readme.io/docs/integration-overview

Integrate the payment solution, passing payment information, theme, and locale as data attributes. The 'data-locale' attribute accepts standard locale codes.

```javascript
<script>
    var DATA_INPUT = '<?xml+version="1.0"+encoding="UTF-8"+standalone="yes"?>\n<paymentInformation>\n\t<clientReference>TES90</clientReference>\n\t<clientId>1000452465</clientId>\n  <merchantId>0c420d9cae0f4f6f85aaddbde33e8063</merchantId>\n  <merchantSecret>K7jkj12hjhkjbdd</merchantSecret>\n  <buyerCanEdit>true</buyerCanEdit>\n  <returnUrl>https://www.google.com</returnUrl>\n\t<buyer>\n\t\t<id>STUD9001</id>\n\t\t<firstName>James</firstName>\n\t\t<lastName>Bond</lastName>\n\t\t<address>Brooklyn St</address>\n\t\t<city>London</city>\n\t\t<state>London</state>\n\t\t<zip>21121</zip>\n\t\t<country>GBR</country>\n\t\t<email>james.bond@gmail.com</email>\n\t\t<customField>90000</customField>\n\t</buyer>\n\t<service>\n\t\t<id>100000026090</id>\n\t\t<amount>100.90</amount>\n\t</service>\n\t\t<service>\n\t\t<id>100000026091</id>\n\t\t<amount>10.99</amount>\n\t</service>\n</paymentInformation>';
    let themeInfo=JSON.stringify({"primaryColor":"#ff595e","secondaryColor":"#6a4c93","accentColors":["#ff595e","#6a4c93","#2133AF"],"warningColor":"#6a4c93","primaryButtonColor":"\"Jersey 10\", sans-serif","fontName":"\"Jersey 10\", sans-serif","fontUrl":"https://fonts.googleapis.com/css2?family=Jersey+10&display=swap"});
    let sellerInfo = `<convera-payment data-seller-info='${DATA_INPUT}' data-theme='${themeInfo}' data-locale="fr_FR"></convera-payment>`
    $('#sellerInput').html(sellerInfo);
</script>
```

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

### Get Settlement Currencies API

Source: https://convera.readme.io/docs/option-2-customer-model-2-overview

Retrieves a list of settlement currencies available for the client. These are the currencies that can be used for settlement and are configured within the client's 'Holding' settings.

```APIDOC
## Get Settlement Currencies

### Description
To provide a list of settlement currencies for the payer to choose from; this list is associated to the currencies declared to be used by the client, and to be available in ‘Holding’.

### Method
GET

### Endpoint
/settlement-currencies

### Parameters
#### Query Parameters
- **gpfiClientId** (string) - Required - The unique identifier for the GPFI client.

### Response
#### Success Response (200)
- **settlementCurrencies** (array) - A list of available settlement currencies.
```