Skip to main content
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
Response Body
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
Response Body
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
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
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
Response Body
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
Response Body
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
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