> ## Documentation Index
> Fetch the complete documentation index at: https://docs.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant-Managed APIs

Merchants using a Merchant-managed flow are required to process and respond to these APIs. This section provides definitions and examples for each API request, as well as design considerations.

The APIs used for integration with Partner Ecosystem Management are the MarketONE APIs.

The Merchant's system must support idempotency for successful subscription status management.

**Note:** Include the corresponding Reseller-specific API key in the HTTP header for each call.

## POST /partnerSubscription

This API is used to create a billing partner relationship.

In addition to the request body, the Merchant must also provide the Reseller (Service Provider) organization code in the HTTP header or query parameter.

**Request Body**

```
{
  "identifierType": <Enum>, //account identifier type
  "identifier": "<identifier value>", //The corresponding account identifier value
  "plmCode": "<MarketONE OpenAPI internal ID for Merchant product>",
  "partnerCode": "<MarketONE OpenAPI internal ID for the Merchant>"
}
```

**Response Body**

```
{
  "id": "<Partner subscription ID>",
  "organizationId": "<code for the organization through which the user is payment is billed against>"
  "partnerCode": "<MarketONE OpenAPI internal ID for the Merchant, same as the partnerCode from request>",
  "createdDate": "<date and time the Partner subscription record was created>",
  "billingStatus": "<the Partner subscription status in MarketONE OpenAPI>", //The value could be PENDING-VALIDATION or PENDING-CONFIRMATION (if PIN validation is skipped)
  "type": "<type of the Partner subscription record>" //For the Merchant-managed flow, the value is always BILLING
}
```

**Design Considerations**

1. The Merchant should support at least one of the following account identifier types: email or mobile. The Reseller (Service Provider) uses the identifier(s) for account validation.
2. The Merchant is required to handle error responses from account validation on the Reseller's (Service Provider's) side.
3. **Idempotency and fraud prevention**

   `POST /partnerSubscription` is idempotent (that is, it doesn't alter or change the result for the same call). The Merchant must be able to detect potential fraud by analyzing the result of `POST /partnerSubscription`.

   Example scenario:

   1. User A selects pay with bill and provides an account identifier (for example, a mobile number). The Merchant calls `POST /partnerSubscription` to do the account validation. Upon checking with the Reseller's (Service Provider's) BSS system for account eligibility, MarketONE returns a `partnerSubscriptionID` and `PENDING-VALIDATION` status. The Merchant goes through PIN validation and confirmation before posting a charge, as per the standard flow. At this point, the `partnerSubscription` status is `ACTIVE`.

   2. Now User B signs up with the Merchant and selects pay with bill, but instead of entering their own account identifier, they enter the identifier of User A. (They knew or stole User A's account identifier.) Now `POST /partnerSubscription` has exactly the same parameter as it does for User A, so MarketONE returns the same `partnerSubscriptionID` and an `ACTIVE` status. From the Merchant's perspective, the `partnerSubscription` is meant to be in `PENDING-VALIDATION` status. The same `partnerSubscriptionID` has been associated with User A, but now User B is trying to link their purchase with the same `partnerSubscriptionID`, and it should be marked as potential fraud by the Merchant.
      There are two assumptions that help with fraud detection:

   3. The Merchant is managing the users. When the user either signs in or signs up, the Merchant receives unique user identities and therefore should be able to differentiate User A and User B in the above example scenario.

   4. The Merchant needs to persist the `partnerSubscriptionID` for a given user/subscription because the same ID is required not only for PIN validation and confirmation, but also for the recurring charges (`partnerSubscriptionID` must be provided for `POST /transaction` calls). As such, the Merchant is able to detect whether a `partnerSubscriptionID` is being associated with a second user.

## POST /partnerSubscription/\{id}/validate

This API is used to validate the PIN generated by MarketONE against the value entered by the user. This API verifies the user's identity.

The PIN is generated by MarketONE OpenAPI. However, the Reseller (Service Provider) notification system sends the PIN to the user. The Reseller (Service Provider) notification system has the contact information of the account owner.

The `id` parameter is the `partnerSubscriptionID` from the original `POST /partnerSubscription` call.

**Request Body**

```
{
  "pin": "<pin code the user entered>"
}
```

**Response Body**

```
{  
  "id": "<Partner subscription ID>",
  "organizationId": "<code for the organization through which the user is payment is billed against>"
  "partnerCode": "<MarketONE OpenAPI internal ID for the Merchant, same as the partnerCode from request>",
  "createdDate": "<date and time the Partner subscription record was created>",
  "billingStatus": "<the Partner subscription status in MarketONE OpenAPI>", //The value is PENDING-CONFIRMATION (or ACTIVE if the confirmation API is skipped)
  "type": "<type of the Partner subscription record>" //For the Merchant-managed flow, the value is always BILLING
}
```

**Design Considerations**

1. It's a best practice to verify the user identity via the PIN (that is, to include this call in the subscription flow design).
2. The Merchant is responsible for handing retries if the user entered the wrong PIN.

## POST /partnerSubscription/\{id}/confirm

This API is used to confirm the billing partner subscription.

The `id` parameter is the `partnerSubscriptionID` from the original `POST /partnerSubscription` call. No request body is required for this call.

**Note:** This API is optional. If the Merchant chooses not to use this API, it will be configured in MarketONE so that `POST partnerSubscription/{id}/validate` returns an `ACTIVE` status instead.

**Response Body**

```
{  
  "id": "<Partner subscription ID>",
  "organizationId": "<code for the organization through which the user is payment is billed against>"
  "partnerCode": "<MarketONE OpenAPI internal ID for the Merchant, same as the partnerCode from request>",
  "createdDate": "<date and time the Partner subscription record was created>",
  "billingStatus": "<the Partner subscription status in MarketONE OpenAPI>", //The value is always ACTIVE
  "type": "<type of the Partner subscription record>" //For the Merchant-managed flow, the value is always BILLING
}
```

**Design Considerations**

1. The Merchant must be able to handle error scenarios.

## POST /partnerSubscription/\{id}/resend

This API is used to request that the PIN be re-sent to the user.

The `id` parameter is the `partnerSubscriptionID` from the original `POST /partnerSubscription` call. No request body is required for this call.

**Response Body**

```
{  
  "id": "<Partner subscription ID>",
  "organizationId": "<code for the organization through which the user is payment is billed against>"
  "partnerCode": "<MarketONE OpenAPI internal ID for the Merchant, same as the partnerCode from request>",
  "createdDate": "<date and time the Partner subscription record was created>",
  "billingStatus": "<the Partner subscription status in MarketONE OpenAPI>", //The value is always PENDING-VALIDATION
  "type": "<type of the Partner subscription record>" //For the Merchant-managed flow, the value is always BILLING
}
```

**Design Considerations**

1. The Merchant is responsible for offering the resend option in case the user didn't receive the PIN.
2. The Merchant is also responsible for letting the user know whether the PIN validation is successful or needs a retry.

## POST /transaction

The Merchant uses this API to post the charges of a subscription to MarketONE and MarketONE relays the charge to the Reseller (Service Provider).

This API is used for one-time charges and recurring charges. For recurring charges, Merchants are responsible for posting the charge at the beginning of each billing cycle.

**Request Body**

```
{  
  "id": "<transaction ID from Merchant>",
  "amount": <amount of the subscription charge>,
  "created": "<timestamp of the transaction>",
  "currency": "<currency in ISO 4217 format>",
  "partnerSubscription metadata": {<key value pair for additional information>},
  "items": [<array of transaction items belonging to this transaction. one for actual amount and the other for tax amount>]
}
```

**Response Body**

```
{  
  "id": "<transaction ID from Merchant>",
  "extConfirmationId": "<corresponding transaction ID generated by MarketONE OpenAPI>",
  "Status": "<status of the transaction>"
}
```

**Design Considerations**

1. It's the responsibility of the Merchant to post the charge whenever the recurring charge is due. For example, if a user subscribed to the Merchant's monthly service on November 1, the first `POST /transaction` happens at the point of subscription. Going forward, whenever it's the first day of the month, the Merchant must call `POST /transaction` to post charges for that particular subscription of the same user.

## POST /transaction/\{id}/refund

The Merchant uses this API to post the refund of the subscription to MarketONE and MarketONE relays the refund to the Reseller (Service Provider).

The `id` in the parameter is the original transaction `id` of `POST /transaction` call.

**Request Body**

```
{  
  "id": "<transaction ID from Merchant>",
  "amount": <amount of the subscription charge, must be a positive value>,
  "created": "<timestamp of the transaction>",  
  "currency": "<currency in ISO 4217 format>",
  "note" : "<free form description>",
  "reasonCode": "<Enumeration value for refund reason>"
  "partnerSubscription metadata": {<key value pair for additional information>},
  "refund_items": [<array of itemized refund with details>]
}
```

**Response Body**

```
{  
  "id": "<transaction ID from Merchant, it is a different ID than the original transaction ID because refund itself is also a transaction>",
  "extConfirmationId": "<corresponding transaction ID generated by MarketONE OpenAPI>"
  "Status": "<status of the refund transaction>"
}
```

**Design Considerations**

1. After the Merchant posts a refund for a subscription, MarketONE performs the validation to make sure the refund amount doesn't exceed the original charge amount on the same Partner subscription.
2. The Merchant is required to handle any potential error responses from MarketONE.

## POST /partnerSubscription/\{id}/cancel

This API is used to cancel an active billing partner subscription relationship.

The `id` in the parameter is the original `partnerSubscriptionID`. No response body is required for this call.

**Response Body**

```
{  
  "id": "<Partner subscription ID>",
  "organizationId": "<code for the organization through which the user is payment is billed against>"
  "partnerCode": "<MarketONE OpenAPI internal ID for the Merchant, same as the partnerCode from request>",
  "createdDate": "<date and time the Partner subscription record was created>",
  "billingStatus": "<the Partner subscription status in MarketONE OpenAPI>", //The value is always CANCELLED
  "type": "<type of the Partner subscription record>" //For the Merchant-managed flow, the value is always BILLING
}
```

**Design Considerations**

1. Technically, when a subscription is canceled through the Merchant, the Merchant can stop sending the recurring `POST /transaction` call for that subscription. However, in MarketONE, the Partner subscription is still active, so this incurs a data discrepancy. This cancellation call makes sure the status in MarketONE is in sync.
2. The Merchant is required to handle any potential error response from MarketONE.

**Parent topic:**[Design Guidelines for the Merchant-Managed Flow](designGuidelinesPartnerManaged)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.