# Payments
source: https://developer.mastercard.com/community-pass-payment-apis/documentation/parameters/donors/index.md

### Merchant Payments (B2B) \& Customer Payments (B2C) {#merchant-payments-b2b--customer-payments-b2c}

These APIs helps Suppliers/Organizations making payments to individual farmers/beneficiaries and Parents making low-value payments of school fees to schools to validate of beneficiaries and notify the payment status information to the application hosted inside Mastercard.

## Payments Callbacks {#payments-callbacks}

### Create payments callbacks {#create-payments-callbacks}

This API will be called by the payment provider and will enable the application hosted inside Mastercard to know the exact status of the payment transaction initiated.

| Method |      Endpoint       |
|--------|---------------------|
| POST   | /payments/callbacks |

Note: The Request Body has to be encrypted!

### Request Body {#request-body}

|           Name           |        Type        |                              Description                               |    Notes     |
|--------------------------|--------------------|------------------------------------------------------------------------|--------------|
| **appId**                | string             | Application identifier for client.                                     | **Required** |
| **partnerAccountId**     | string             | An id provided by the payment provider to identify the source account. | **Required** |
| **transactionReference** | string             | Transaction reference generated by client.                             | **Required** |
| **providerReference**    | string             | Provider reference generated by provider.                              | **Required** |
| **responseCode**         | string             | Provider response code.                                                | **Required** |
| **responseMessage**      | string             | Provider response message.                                             | **Required** |
| **correlationId**        | string             | Unique identifier to track payment request.                            | **Required** |
| **recipients**           | array\[Recipient\] | Payment recipients.                                                    | **Required** |

### Child Attributes {#child-attributes}

#### recipients {#recipients}

|         Name          |  Type  |                                  Description                                   |    Notes     |
|-----------------------|--------|--------------------------------------------------------------------------------|--------------|
| **requestId**         | string | Request id generated for each beneficiary transaction by orchestrator.         | **Required** |
| **transactionId**     | string | Transcation id generated for each beneficiary transaction by payment provider. | **Required** |
| **accountName**       | string | Payer Name.                                                                    | **Required** |
| **accountNumber**     | string | Destination account number.                                                    | **Required** |
| **transactionAmount** | string | TransactionAmount amount.                                                      | **Required** |
| **currency**          | string | Alphabetic code of currency as per ISO4217 standard.                           | **Required** |
| **countryCode**       | string | ISO 3-alpha country code format.                                               | **Required** |
| **responseCode**      | string | ResponseCode of the transaction.                                               | **Required** |
| **responseMessage**   | string | ResponseMesage of the transaction.                                             | **Required** |

### Create payments callback request {#create-payments-callback-request}

```JSON
{
  "appId": "MFN",
  "partnerAccountId": "12345678",
  "transactionReference": "ref-123-456",
  "providerReference": "pro-1233763",
  "responseCode": "100",
  "responseMessage": "Successful",
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "recipients": [
    {
      "requestId": "8387484747",
      "transactionId": "7253653653",
      "accountName": "Test User",
      "accountNumber": "1234567890",
      "transactionAmount": 1500,
      "currency": "USD",
      "countryCode": "USA",
      "responseCode": "100",
      "responseMessage": "successful"
    }
  ]
}
```

### Response Fields {#response-fields}

A successful request returns the `HTTP 200 OK` status code.

## Payments Validations {#payments-validations}

### Create payments validations {#create-payments-validations}

This API can be used by payment provider to validate payment related information present inside the Mastercard system.

| Method |       Endpoint        |
|--------|-----------------------|
| POST   | /payments/validations |

Note: The Request Body has to be encrypted!

### Request Body {#request-body-1}

|        Name         |  Type  |                    Description                     |    Notes     |
|---------------------|--------|----------------------------------------------------|--------------|
| **appId**           | string | Application identifier for client.                 | **Required** |
| **partnerId**       | string | Code to identify partner.                          | **Required** |
| **accountId**       | string | Account Number being validated. E.g: student id.   | **Required** |
| **partnerType**     | string | Partner type can be SCHOOL/BUYER/CHANNEL/SUPPLIER. | **Required** |
| **correlationId**   | string | Unique identifier to track payment request.        | **Required** |
| **transactionTime** | string | Transaction time.                                  | **Required** |
| **paymentChannel**  | string | Depicts mode of payment (MOBILE or BANK).          | **Required** |

### Create payments validation request {#create-payments-validation-request}

```JSON
{
  "appId": "MFN",
  "partnerId": "12345",
  "accountId": "25471234567",
  "partnerType": "SCHOOL",
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "transactionTime": "2020-07-16T19:20:30+01:00",
  "paymentChannel": "MOBILE"
}
```

### Response Fields {#response-fields-1}

Note: The Response Body is encrypted, it should be decrypted to view the actual response fields!

### PaymentValidationStatus {#paymentvalidationstatus}

|        Name        |  Type  |                   Description                    |    Notes     |
|--------------------|--------|--------------------------------------------------|--------------|
| **accountId**      | string | Account Number being validated. E.g: student id. | **Required** |
| **accountName**    | string | Payer Name.                                      | **Required** |
| **additionalInfo** | object | Additional info.                                 | **Required** |

### Child Attributes {#child-attributes}

### PaymentValidationStatus.AdditionalInfo {#paymentvalidationstatusadditionalinfo}

|     Name     |  Type  |                     Description                      |    Notes     |
|--------------|--------|------------------------------------------------------|--------------|
| **balance**  | string | Account balance.                                     | **Required** |
| **currency** | string | Alphabetic code of currency as per ISO4217 standard. | **Required** |

### PaymentValidation Response {#paymentvalidation-response}

```JSON
{
  "accountId": 25471234567,
  "accountName": "Student Name",
  "additionalInfo": {
    "balance": 1500,
    "currency": "UGX"
  }
}
```

## Payments Notifications {#payments-notifications}

### Create payments notifications {#create-payments-notifications}

This API can be used by payment provider to notify Mastercard system in case of payment initiated from an external application.

| Method |        Endpoint         |
|--------|-------------------------|
| POST   | /payments/notifications |

Note: The Request Body has to be encrypted!

### Request Body {#request-body-2}

|         Name          |  Type  |                     Description                      |    Notes     |
|-----------------------|--------|------------------------------------------------------|--------------|
| **appId**             | string | Application identifier for client.                   | **Required** |
| **partnerId**         | string | Code to identify partner.                            | **Required** |
| **providerReference** | string | Unique transaction ID from Payment Provider.         | **Required** |
| **sourceAccount**     | string | Payer mobile bank account number.                    | **Required** |
| **paymentChannel**    | string | Depicts mode of payment (MOBILE or BANK).            | **Required** |
| **transactionAmount** | string | Transaction amount.                                  | **Required** |
| **accountId**         | string | Payer's account id.                                  | **Required** |
| **transactionDate**   | string | Transaction date in the format 'YYYY-MM-DD'.         | **Required** |
| **narration**         | string | Description of payment.                              | **Required** |
| **accountName**       | string | Payer Name.                                          | **Required** |
| **accountNumber**     | string | Destination account number.                          | **Required** |
| **currency**          | string | Alphabetic code of currency as per ISO4217 standard. | **Required** |
| **countryCode**       | string | ISO 3-alpha country code format.                     | **Required** |
| **signature**         | string | Request signature.                                   | **Required** |
| **correlationId**     | string | Unique identifier to track payment request.          | **Required** |

### Create payments notification request {#create-payments-notification-request}

```JSON
{
  "appId": "MFN",
  "partnerId": "1234",
  "providerReference": "ABC123",
  "srcAccount": "25471234567",
  "paymentChannel": "MOBILE",
  "transactionAmount": 12567.89,
  "accountId": "1234",
  "transactionDate": "2020-07-15",
  "narration": "Payment for XYZ",
  "accountName": "Payer Name",
  "accountNumber": "25471234589",
  "currency": "UGX",
  "countryCode": "USA",
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

### Response Fields {#response-fields-2}

A successful request returns the `HTTP 201 CREATED` status code.