Pay Now Payment Methods

Payment tokens represent payment methods, such as a credit card number, but do not contain actual payment information. They are generated by the Payment Service and must be added to subscriber or group wallets using the SubMan APIs.

MATRIXX Charging Application does not interpret the value of the payment tokens. Payment tokens are stored in subscriber or group wallets as type BLOB when a subscriber or group is created or updated during subscription management operations.

Payment tokens remain in the subscriber or group wallet until they are removed using the SubMan APIs. Once removed, the token stays in the wallet, but is marked as deleted and cannot be used for subsequent authorizations. When adding a new payment method to a subscriber or group wallet or modifying a payment method using the SubMan APIs, you can specify if the payment method should be the default payment method associated with any Pay Now charges. To set the default payment method, set the IsDefault field to true in the API call. For example: 
<MtxRequestGroupModifyPaymentMethod>
    <GroupSearchData>
        <MtxGroupSearchData>
            <ObjectId>5432</ObjectId>
        </MtxGroupSearchData>
    </GroupSearchData>
    <ResourceId>789</ResourceId>
    <PaymentGatewayUserId>jsmith123</PaymentGatewayUserId>
    <Name>CreditCard</Name>
    <PaymentType>Air Rewards Card</PaymentType>
    <IsDefault>True</IsDefault>
</MtxRequestGroupModifyPaymentMethod>

Only one payment token is designated as the default token. It is automatically set as the default token for the Payment Gateway provider and it is included in the authorization request message to the Payment Service. If a payment method should no longer be the default, set the IsDefault field to false in the API call. To remove a payment method from a subscriber or group, use the RemovePaymentMethod APIs.

When you add a new payment method to a wallet, you can provide a name and a payment type for the payment method. If a name or type is not provided, the Payment Service returns a name and type for the payment method. The payment method name and type is stored in the wallet. If an authorization request uses an existing payment method, the name and type of the payment method are set in the MtxPaymentAuthorizationEvent Event Detail Record (EDR). The payment method name and type are also set in the MtxPaymentSettlementEvent EDR when the transaction is settled, and in the MtxPaymentRefundEvent EDR when the payment is refunded.

When you modify the payment token for an existing payment method in the wallet, you can provide a new name and a new payment type description for the payment method. If a new name or type is not provided, the Payment Service returns a name and type for the payment method. The previous name and type are replaced.

One-Time Tokens

For an authorization request using a one-time token, the payment gateway returns the payment method type, PaymentMethodType, for the one-time token. The payment method type is set in the MtxPaymentAuthorizationEvent and the MtxPaymentSettlementEvent when the transaction is settled. The payment method name is not set in MtxPaymentAuthorizationEvent, MtxPaymentSettlementEvent, or MtxPaymentRefundEvent.

System Payment Methods

In addition to adding payment methods to subscriber and group wallets, you can specify a payment method that is used for system initiated charges (such as auto recharge). If a default system payment method is not set, the default payment method is used for system initiated charges if it is set.

You can define the default payment method for system-initiated charges using the following SubMan APIs:
  • ModifySubscriber
  • ModifyGroup
  • AddPaymentMethod
  • ModifyPaymentMethod

When adding or modifying a payment method using the SubMan APIs, you can set the IsSysDefault field in the request to set or change the default payment method for system initiated charges. If IsSysDefault is set to true, then the payment method being set or modified becomes the new default payment method for system initiated charges. If IsSysDefault is set to false and the payment method being modified is the existing default payment method for system initiated charges, then the payment method being modified will no longer be the default payment method for system initiated charges. If you are modifying a subscriber or group and a system payment method has already been added as the default, you can set the SysPaymentTokenResourceId field to the resource ID of the payment token to be used for system initiated charges.

When querying payment methods, set the ReturnSysDefault field to true to ignore all other payment methods and return only the default payment method for system initiated charges.

For information about validating payment methods, see the discussion about Pay Now payment method validation.