Recurring payment
The payment adapter should be able to accept payment in recurring method. In this payment mode, the payment adapter should create a recurring payment on the payment gateway which charges the subscriber regularly at a particular interval. Methods from the AccessType will be called to payment adapter with certain arguments and we expect the response in same format which is covered here.
We will call the recurring class of the payment adapter where we will pass the credentials details and enviroment of the account. Therefore, payment adapter will always have the payment gateway credentials and other details in every method.
We have already created one payment adapter gem for razorpay payment gateway. In which the accesstype is initializing the razorpay recurring payment as below,
credentials = {'app_key'=>'<APP_KEY_OF_RAZORPAY>', 'secret'=> '<SECRET_KEY_OF_RAZORPAY>', 'enabled'=>true, 'webhook_secret'=>'12345a'}
accesstype_razorpay = AccesstypeRazorpay::Recurring.new(credentials: credentials, environment: '<live or sandbox>')
In the same above manner recurring payment should be done for other payment gateways. Atfer initialization of the recurring class, accesstype will call different instance methods like preview, after_charge, refund_payment, etc.
preview
This method will be called initially by accesstype. Many payment gateways are allowing to create order or subscription before doing the actual payment.
Arguments
- subscription_plan Hash object
- Subscription Plan Object
- subscriber Hash object
- Subscriber Object
- opts Hash object
- It's optional argument and it may contain the payment links or metadata.
Response
It is expecting payment gateway’s order id or subscription id. There would be cases where payment gateway create a subscription without creating any order. In that case, this method should simply return nil as response. The accesstype will understand it nil as valid success response when payment gateway don’t have feature to create any subscription without payment.
In case if payment gateway has the feature to create a subscription before payment, Accesstype will expect a success response as below,
=> #<AccesstypeRazorpay::PaymentResult:0x00007fed5b737a58
@amount_cents=nil,
@amount_currency="",
@external_payment_id="<PAYMENT_TOKEN>",
@international=nil,
@metadata=nil,
@payload=nil,
@payment_gateway_fee=nil,
@payment_gateway_fee_currency=nil,
@payment_token="<PAYMENT_TOKEN>",
@payment_type="razorpay_recurring",
@skip_invoice=nil,
@status=nil,
@success=true>
charge?
This method will return true if the class has charge method. It will return false if the class hasn’t charge method.
Arguments
No arguments will be passed
Response
It will return true or false.
charge
This is not a mandatory method. However, This method needs to be created in payment adapter gem when we need to call API for making payment based on the card details. Many of the payment gateway support this type of flow where user first add the payment details and Backend will call payment api for the transaction. Razorpay payment gateway doesn’t follow this flow, but omise payment gateway do follow this flow.
Arguments
- subscription_plan Hash object
- Subscription Plan Object
- subscriber Hash object
- Subscriber Object
- subscription_attempt Hash object
- Subscription Attempt Object
- payload Hash object
- It will contain the following details `payment_type`, `amount_cents`, `amount_currency`, `payment_token`.
Response
#<AccesstypeRazorpay::PaymentResult:0x00007fa33e48afb0 @payment_type="razorpay", @success=true, @payload=nil, @payment_gateway_fee=1047, @payment_token="SAMPLE_TOKEN", @status="charged", @amount_currency=USD, @amount_cents=1000, @international=nil, @skip_invoice=nil, @metadata=nil, @external_payment_id=nil, @payment_gateway_fee_currency=nil, @external_refund_id=nil>
initiate_charge
This method will initiate the payment . This is only required if the payment cannot be completed in 2 steps ie preview and create subscription calls. This is needed in PGs like adyen where initate_charge sends payment parameters together with the input details collected from the shopper.
Arguments
- payload Hash object
- Initiate Charge Payload Object
- Subscriber Hash object
- Subscriber Object
- Subscription Plan Hash object
- Subscription Plan Object
Response
The Accesstype will expect a success response as below,
#<AccesstypeRazorpay::PaymentResult
@payment_token: 'AB78833',
@payment_gateway_fee: 1000,
@payment_gateway_fee_currency: 'EUR',
@amount_cents: 20000,
@amount_currency: 'EUR',
@metadata: 'tyuis990007888'
@status: 'Success',
@client_payload: {
"pspReference": "8815329842815468",
"resultCode": "Authorised"
} >
after_charge
This method will be called when payment is done on the payment gateway. The accesstype will send a payment token in arguments. The payment adapter will fetch the payment from payment gateway based on the payment token and send response back to the accesstype. This is method will ensure the payment token received to the accesstype is valid.
Arguments
- payment_token String
- payment token received from the payment gateway
Response
The Accesstype will expect a success response as below,
#<AccesstypeRazorpay::PaymentResult:0x00007fa33eeaf360 @payment_type="razorpay_recurring", @success=true, @payload=nil, @payment_gateway_fee=nil, @payment_token="<PAYMENT_TOKEN>", @status=nil, @amount_currency="CNY", @amount_cents=10000, @international=true, @skip_invoice=nil, @metadata=nil, @external_payment_id=nil, @payment_gateway_fee_currency=nil, @external_refund_id=nil>
capture
This method will be called when the accesstype received the success response from the after_charge method. Once we ensure payment is made on payment gateway, we will capture that transaction on payment gateway. It is not mandatory method, some of the payment gateway don’t allow to capture the transacation. If it is not available on the payment gateway, payment adapter can skip it from the integration.
Arguments
- payment Hash object
- Payment Object
Response
The Accesstype will expect a success response as below,
#<AccesstypeRazorpay::PaymentResult:0x00007fa33e48afb0 @payment_type="razorpay", @success=true, @payload=nil, @payment_gateway_fee=1047, @payment_token=nil, @status="captured", @amount_currency=nil, @amount_cents=nil, @international=nil, @skip_invoice=nil, @metadata=nil, @external_payment_id=nil, @payment_gateway_fee_currency=nil, @external_refund_id=nil>
cancel_subscription
This method will be called when the subscription is cancelled from the accesstype dashboard. The accesstype will send payment, consisting payment_token for the subscription. The payment adapter will cancel the subscription from payment gateway and send response back to accesstype.
Arguments
- payment Hash object
- Payment Object
Response
The Accesstype will expect a success response as below,
#<AccesstypeRazorpay::PaymentResult
@message="Subscription cancelled successfully",
@success=true>
recurring_payment
This method is only required when we need to manually renew recurring subscription for each billing period. This is required for payment gateways like adyen
Arguments
- payload Hash object
- Recurring Payment Object
Response
The Accesstype will expect a success response as below,
#<AccesstypeRazorpay::PaymentResult
@payment_token: 'AB78833',
@payment_gateway_fee: 1000,
@payment_gateway_fee_currency: 'EUR',
@amount_cents: 20000,
@status: 'Success',
@payload: {
"pspReference": "8815329842815468",
"resultCode": "Authorised"
} >