Pay Now Authorization Process

The Pay Now authorization occurs when a Payment Gateway Provider approves a payment authorization request sent by the MATRIXX Charging Application.

The Charging Server makes authorization requests through the Payment Service to a Payment Gateway Provider to approve the purchase. The Payment Gateway Provider securely stores the actual payment method and the Charging Server has a secure reference to that data. Payment tokens are provided by the Payment Gateway Provider and stored in subscriber or group wallets in the Charging Server through subscription management operations when creating or updating a subscriber or group. When a payment authorization completes, the Charging Server generates an MtxPaymentAuthorizationEvent Event Detail Record (EDR). If a purchase, postpaid balance payment, or prepaid balance recharge succeeds, an MtxOfferPurchaseNotification, an MtxPaymentNotification, or an MtxRechargeNotification notification is generated.

For more information about payment authorization events, see the discussion about payment authorization events. For more information about notifications, see the discussion about the Notification Framework in MATRIXX Integration.

MATRIXX Pay Now Authorization Process illustrates the Pay Now authorization process.

Figure 1. MATRIXX Pay Now Authorization Process
The Pay Now process typically follows these steps:
  1. The client uses the SubMan APIs to purchase a product offer (or bundle) and the subscriber data is updated with the product offer. The wallet is updated with any new balances and charges and grants to specific balances are calculated.
    Note: The same blade and socket that processes the purchase request also sends the purchase response.
  2. For product offers or bundles with a payment method of Pay Now, MATRIXX Charging Application sends a payment authorization request message with the payment method token, the amount, and the Merchant Account ID to the producer queue through the ActiveMQ Gateway. The Payment Service retrieves the payment authorization request from the producer queue and sends it to the Payment Gateway Provider. For information about Merchant Account IDs, see the discussion about Pay Now payment method configuration.
    Note: Communication with the Payment Service is asynchronous.
  3. The Payment Gateway Provider sends a payment authorization result through the Payment Service. If the result is success, the result includes the payment transaction ID. The Payment Service sends the payment authorization response to the consumer queue.

    If the payment authorization result is not received within 10 seconds, the payment authorization fails. For a complete description of MATRIXX Engine architecture, see MATRIXX Architecture.

  4. The ActiveMQ Gateway retrieves the payment authorization response and if the authorization was successful, the purchase is completed. Note that the main balance (specified in the balance template) is not charged for the Pay Now purchase.
    Note: In situations where a payment has been authorized but the authorization is not received and processed by MATRIXX Engine, the engine times out waiting for the response from the Payment Gateway Provider and the purchase operation fails. The payment authorization eventually times out because it is never settled.
  5. A response is sent to the client that initiated the purchase. The same server and socket that process the purchase request also send the purchase response.

If a Payment Gateway Provider supports a single operation for both authorization and settlement, MATRIXX Charging Application always performs the authorization and settlement in a single operation. For example, MATRIXX Charging Application always performs authorization and settlement as a single operation for the Braintree Payment Gateway Provider. After authorization is complete, MATRIXX Charging Application generates an MtxPaymentAuthorizationEvent EDR. When there is a single operation for both authorization and settlement, the MtxPaymentAuthorizationEvent PaymentSettled field is set to true. If true, a separate MtxPaymentSettlementEvent EDR is not generated.

A Payment Gateway Provider may return specific information during an authorization transaction. This information is returned in the Subman API response to the request (purchase, payment, or recharge) that triggered the authorization.

The Payment Gateway Provider response is included in the PaymentGatewayResponseAttr field of type MtxPaymentGatewayResponseExtension. A Braintree-specific MATRIXX Data Container (MDC) that extends MtxPaymentGatewayResponseExtension, MtxBraintreeResponseExtension, includes information from the Braintree Payment Gateway Provider. The information is included in the SubMan API response for authorization success and failure. For example, when Paypal is the payment method, the MtxBraintreeResponseExtension includes two additional parameters, paypalAuthorizationId and paypalCatureId.

The Payment Gateway Provider response information is also included in the MtxPaymentAuthorizationEvent EDR. The PaymentGatewayResultAttr field of type MtxPaymentGatewayResultExtension holds this response information. The following MDCs include provider-specific information that is included in the MtxPaymentAuthorizationEvent EDR for authorization success and failure.
  • MtxBraintreeResultExtension Fields includes optional information from the Braintree Payment Gateway Provider.
    Table 1. MtxBraintreeResultExtension Fields
    Name Type Description
    RiskDataId String ID of Risk data.
    RiskDataDecision String Decision of Risk data.
    RiskDataDeviceDataCaptured Bool DeviceDataCaptured of Risk data.
    ThreeDSecureEnrolled String Indicates whether a card is enrolled in a 3D.
    ThreeDSecureLiabilityShifted Bool Indicates whether the liability shifted or not.
    ThreeDSecureLiabilityShiftPossible Bool Indicates whether a liability shift is possible.
    ThreeDSecureStatus String The 3D Secure status value.
    PaypalAuthorizationId String Paypal Authorization ID.
    PaypalCaptureId String Paypal Capture ID.
    ProcessorResponseCode String Processor Response Code.
    ProcessorResponseText String Processor Response Text.
    ProcessorResponseType Unsigned int32

    ProcessorResponseSubType

    		 Processor Response Type:
    • APPROVED (0)
    • SOFT_DECLINED (1)
    • HARD_DECLINED (2)
    • UNRECOGNIZED (3)
    ProcessorSettlementResponseCode String Processor Settlement Response Code.
    ProcessorSettlementResponseText String Processor Settlement Response Text.
    AuthorizationExpiresAt Datetime Authorization Expires At.
    GatewayRejectionReason String Gateway Rejection Reason.
    IsTxnSettled Bool Indicates whether the transaction has settled.
    OrderId String The unique order ID used in the authorise or settlement request. This can be used to track the transaction and aids duplicate checking.
    PaymentReason String The payment reason.
  • Foo Payment Gateway Provider Result Extension Fields includes the following optional information from the Foo Payment Gateway Provider.
    Table 2. Foo Payment Gateway Provider Result Extension Fields
    Name Type Description
    ClientId String Client ID
    TxnId String Transaction ID
    CorrelationId String Correlation ID
    Status String Status
    StatusCode Unsigned int16 Status code
    AuthorizationId String Authorize ID
    ReceiptNo String Receipt No
    TxnAmount Decimal Transaction Amount
    PrimaryAccountNo String Masked Primary Account Number
    Msg String Message
    TxnCurrency String Transaction Currency
    TxnReceipt String Transaction Receipt
    BankMerchantId String Bank Merchant ID
    CardScheme String Card Scheme
    IssuerBankName String Issuer Bank Name
  • MtxRomcardPaymentGatewayResultExtension Fields includes optional information from the RomCard Payment Gateway Provider.
    Table 3. MtxRomcardPaymentGatewayResultExtension Fields
    Name Type Description
    Status String Status
    ErrorCode String Error Code
    Msg String Message
    AlternativeErrorCode String ISO 8583 Error Code
    AlternativeErrorMsg String ISO 8583 Error Message
    TxnId String Transaction ID
    Variable String Variables

You can customize the information that is included in the MtxBraintreeResponseExtension and MtxPaymentGatewayResultExtension MDCs. For more information about extending MDCs, see the discussion about extending MATRIXX Engine functionality in MATRIXX Installation and Upgrade. For information about the MtxBraintreeResponseExtension MDC, see MATRIXX Integration.