# Scheduled Merchant-Initiated Transaction scenario
Merchant can initiate payment transaction using stored credentials on a fixed schedule and using a fix amount. Below, decribes a possible scenario
# Step 1 - Initial payment
- Cardholder buy a subscription from your store for the first time and agrees to place their card on file with the merchant. (The cardholder should be charge a fix amount every month for a period of 1 year)
- The cardholder performs a payment by entering their full card details.
- If the merchant is PCI SAQ-D Compliant, he can perform a full card payment else he should perform the payment using a payment-nonce.
- As it is the initial payment, the transaction is initiated by the cardholder. (set the flag
merchant_initiatedtofalsein the payment request payload). We also need to indicate that the transaction is part of a subscription by setting thetransaction.type: 2in the payload.
Note
transaction.type: 1- Regular transactiontransaction.type: 2- Subscription or recurring transaction
TIP
Request example
- Shell
- JavaScript
curl -X POST \
https://api.ompay.com/v1/merchants/w3z8dfhkzvfq0j9n/payment \
-H 'authorization: Basic ODZidWQ0Y2JremlxOXZmYzoweHI1ZDkwOHo2bmo4a2h6' \
-H 'content-type: application/json' \
-d '{
"intent": "auth",
"merchant_initiated": false,
"payer": {
"payment_type": "CC",
"funding_instrument": {
"credit_card": {
"number": "4005520201264821",
"expire_month": 12,
"expire_year": 2020,
"cvv2": "123",
"name": "Tom Hanks",
}
},
"payer_info": {
"email": "TomHanks@gmail.com",
"billing_address": {
"line1": "18 Avenue",
"line2": "cassidy",
"city": "Rose-Hill",
"country_code": "mu",
"postal_code": "72101",
"state": "",
"phone": {
"country_code": "230",
"number": "57976041"
}
}
}
},
"payee": {
"email": "mail@test.com",
"merchant_id": "w3z8dfhkzvfq0j9n"
},
"transaction": {
"type": 2,
"amount": {
"currency": "USD",
"total": "300",
"details": {
"subtotal": "",
"shipping": ""
}
},
"description": "purchase",
"items": [{
"sku": "100299S",
"name": "Ultrawatch",
"description": "Smart watch",
"quantity": "1",
"price": "500",
"shipping": "20",
"currency": "USD",
"url": "",
"image": "",
"tangible": "true"
},
{
"sku": "100269S",
"name": "Drone",
"description": "drone x",
"quantity": "1",
"price": "500",
"shipping": "20",
"currency": "USD",
"url": "",
"image": "",
"tangible": "true"
}
],
"shipping_address": {
"recipient_name": "Tom Hanks"
},
"soft_descriptor": {
"text": "test.com",
"city": "london"
},
"invoice_number": "123455"
},
"custom": {
},
"capture_delay": 0.05,
"metadata": {
"CMS": "WooCommerce"
}
}'
Response example
{
"id": "2JHY1CB6CR8N0FZK43WU",
"reference_id": "2JHY1CB6CR8N0FZK43WU",
"state": "authorised",
"result": {
"authorisation_code": "590622",
"code": "0000",
"description": "Approved"
},
"intent": "AUTH",
"payer": {
"payment_type": "CC",
"funding_instrument": {
"credit_card": {
"id": "20abc6eb-35fd-427e-b57e-c7eea99dd423",
"type": "Visa",
"expire_month": 6,
"expire_year": 2025,
"name": "Tom Hanks",
"cvv_check": "Y",
"avs_check": "S",
"last4": "9996",
"bin": "454347",
"bin_data": {
"bin": "454347",
"country_code": "MU",
"country_name": "Mauritius",
"bank_name": "MCB",
"card_scheme": "Visa",
"card_type": "Credit",
"card_category": "1"
}
}
},
"payer_info": {
"id": "35d4d1ec-4f9d-416d-acdc-d12f4bf0c6df",
"email": "tomhank@gmail.com",
"name": "Tom Hanks",
"billing_address": {
"phone": {
"country_code": "230",
"number": "57976041"
},
"line1": "18 Avenue",
"line2": "cassidy",
"city": "Rose-Hill",
"country_code": "MU",
"postal_code": "72101",
"state": ""
}
}
},
"transaction": {
"amount": {
"currency": "USD",
"total": "300"
},
"type": "1",
"mode": "1",
"items": [
{
"sku": "100299S",
"name": "Ultrawatch",
"description": "Smart watch",
"quantity": "1",
"price": "500",
"shipping": "",
"url": ""
},
{
"sku": "100269S",
"name": "Drone",
"description": "drone x",
"quantity": "1",
"price": "500",
"shipping": "",
"url": ""
}
],
"shipping_address": {
"phone": {}
},
"invoice_number": "123455"
},
"custom": {},
"risk_check": true,
"three_d": {},
"create_time": "2023-06-09T18:07:37Z",
"subscriptions": null
}
# Step 2 - Save card or card ID
If the merchant is managing the recurring payment flow inhouse, They might need to save the reference_id from the initial payment for future use.
For PCI SAQ-D merchants, they might choose to save the full card details on their servers.
For non PCI merchants, they might choose to save the
payerdetails and associatedpayer.funding_instrument.credit_card.id.# Step 3 - Recurring payment
Merchants with custom recurring payment flow will, on the next billing date, initiate a recurring payment without the interaction of the payer.
To initiate subsequent scheduled merchant initiated transaction (the flag merchant_initiated should be set to true). We also need to indicate that the transaction is part of a subscription by setting the transaction.type: 2 (2 - Subscription) and referencing the initial payment by setting he parameter previous_payment_id:<reference_id> using the saved reference_id.
# For PCI SAQ-D merchants
If the merchant is PCI SAQ-D and stores the card details on his own server. The merchant will perform a full card payment with the following flag .
merchant_initiated: trueprevious_payment_id: <reference_id>payer.funding_instrument.credit_card.stored: true
# Authorize a second payment using full card details
Request example
curl -X POST \
https://api.ompay.com/v1/merchants/w3z8dfhkzvfq0j9n/payment \
-H 'authorization: Basic ODZidWQ0Y2JremlxOXZmYzoweHI1ZDkwOHo2bmo4a2h6' \
-H 'content-type: application/json' \
-d '{
"intent":"auth"
,"merchant_initiated":true
,"previous_payment_id": "2JHY1CB6CR8N0FZK43WU"
,"payer":{
"payment_type":"CC"
,"funding_instrument":{
"credit_card":{
"number":"4005520201264821"
,"expire_month":12
,"expire_year":2020
,"cvv2":"123"
,"name":"Tom Hanks"
,"stored":true
}
}
,"payer_info":{
"email":"TomHanks@gmail.com"
,"billing_address":{
"line1":"18 Avenue"
,"line2":"cassidy"
,"city":"Rose-Hill"
,"country_code":"mu"
,"postal_code":"72101"
,"state":""
,"phone":{
"country_code":"230"
,"number":"57976041"
}
}
}
}
,"payee":{
"email":"mail@test.com"
,"merchant_id":"w3z8dfhkzvfq0j9n"
}
,"transaction":{
"type": 2
,"amount":{
"currency":"USD"
,"total":"300"
,"details":{
"subtotal":""
,"shipping":""
}
}
,"description":"purchase"
,"items":[
{
"sku":"100299S"
,"name":"Ultrawatch"
,"description":"Smart watch"
,"quantity":"1"
,"price":"500"
,"shipping":"20"
,"currency":"USD"
,"url":""
,"image":""
,"tangible":"true"
},
{
"sku":"100269S"
,"name":"Drone"
,"description":"drone x"
,"quantity":"1"
,"price":"500"
,"shipping":"20"
,"currency":"USD"
,"url":""
,"image":""
,"tangible":"true"
}
]
,"shipping_address":{
"recipient_name":"Tom Hanks"
}
,"soft_descriptor":{
"text":"test.com"
,"city":"london"
}
,"invoice_number":"123455"
}
,"custom":{
},
"capture_delay": 0.05,
"metadata":{
"CMS":"WooCommerce"
}
}'
Response example
{
"id": "123Y1CB6CR8N0FZK43WU",
"reference_id": "2JHY1CB6CR8N0FZK43WU",
"state": "authorised",
"result": {
"authorisation_code": "590622",
"code": "0000",
"description": "Approved"
},
"intent": "AUTH",
"payer": {
"payment_type": "CC",
"funding_instrument": {
"credit_card": {
"id": "20abc6eb-35fd-427e-b57e-c7eea99dd423",
"type": "Visa",
"expire_month": 6,
"expire_year": 2025,
"name": "Tom Hanks",
"cvv_check": "Y",
"avs_check": "S",
"last4": "9996",
"bin": "454347",
"bin_data": {
"bin": "454347",
"country_code": "MU",
"country_name": "Mauritius",
"bank_name": "MCB",
"card_scheme": "Visa",
"card_type": "Credit",
"card_category": "1"
}
}
},
"payer_info": {
"id": "35d4d1ec-4f9d-416d-acdc-d12f4bf0c6df",
"email": "tomhank@gmail.com",
"name": "Tom Hanks",
"billing_address": {
"phone": {
"country_code": "230",
"number": "57976041"
},
"line1": "18 Avenue",
"line2": "cassidy",
"city": "Rose-Hill",
"country_code": "MU",
"postal_code": "72101",
"state": ""
}
}
},
"transaction": {
"amount": {
"currency": "USD",
"total": "300"
},
"type": "1",
"mode": "1",
"items": [
{
"sku": "100299S",
"name": "Ultrawatch",
"description": "Smart watch",
"quantity": "1",
"price": "500",
"shipping": "",
"url": ""
},
{
"sku": "100269S",
"name": "Drone",
"description": "drone x",
"quantity": "1",
"price": "500",
"shipping": "",
"url": ""
}
],
"shipping_address": {
"phone": {}
},
"invoice_number": "123455"
},
"custom": {},
"risk_check": true,
"three_d": {},
"create_time": "2023-06-09T18:07:37Z",
"subscriptions": null
}
# For Non PCI merchants
# Step 1: Retrieve payers associated cards
if the merchant is not PCI SAQ-D and uses our Vault to store credit card details. The merchant will need to specify the credit_card_id retrieved and stored from the initial payment.
TIP
- For more information on retrieving card details, please refer to this page.
# Step 2: Authorize a subsequent payment using card_id
Request example
curl -X POST \
http://api.ompay.com/v1/merchants/w3z8dfhkzvfq0j9n/payment \
-H 'authorization: Basic ODZidWQ0Y2JremlxOXZmYzoweHI1ZDkwOHo2bmo4a2h6' \
-H 'content-type: application/json' \
-d '{
"intent": "auth",
"merchant_initiated": true,
"previous_payment_id": "2JHY1CB6CR8N0FZK43WU",
"payer": {
"payment_type": "CC",
"funding_instrument": {
"credit_card_token": {
"credit_card_id": "20abc6eb-35fd-427e-b57e-c7eea99dd423"
}
},
"payer_info": {
"email": "testclient@gmail.com",
"billing_address": {
"line1": "18 Avenue",
"line2": "Test",
"city": "city name",
"country_code": "GB",
"postal_code": "W1 2",
"state": "",
"phone": {
"country_code": "+1",
"number": "0900099990"
}
}
}
},
"payee": {
"email": "mail@merchantdomain.com",
"merchant_id": "w3z8dfhkzvfq0j9n"
},
"transaction": {
"type": 2,
"amount": {
"currency": "USD",
"total": "200.00",
"details": {
"subtotal": "",
"shipping": ""
}
},
"description": "purchase",
"items": [{
"sku": "100299S",
"name": "Ultrawatch",
"description": "Smart watch",
"quantity": "1",
"price": "110.00",
"shipping": "20",
"currency": "USD",
"url": "",
"image": "",
"tangible": "true"
},
{
"sku": "100269S",
"name": "Drone",
"description": "drone x",
"quantity": "2",
"price": "45",
"shipping": "20",
"currency": "USD",
"url": "",
"image": "",
"tangible": "true"
}
],
"shipping_address": {
"recipient_name": "Tom Hanks"
}
,
"invoice_number": "123455"
},
"custom": {
"field1": "this is a test"
}
}'
Response example
{
"id": "123Y1CB6CR8N0FZK43WU",
"reference_id": "2JHY1CB6CR8N0FZK43WU",
"state": "authorised",
"result": {
"authorisation_code": "590622",
"code": "0000",
"description": "Approved"
},
"intent": "AUTH",
"payer": {
"payment_type": "CC",
"funding_instrument": {
"credit_card": {
"id": "20abc6eb-35fd-427e-b57e-c7eea99dd423",
"type": "Visa",
"expire_month": 6,
"expire_year": 2025,
"name": "Tom Hanks",
"cvv_check": "Y",
"avs_check": "S",
"last4": "9996",
"bin": "454347",
"bin_data": {
"bin": "454347",
"country_code": "MU",
"country_name": "Mauritius",
"bank_name": "MCB",
"card_scheme": "Visa",
"card_type": "Credit",
"card_category": "1"
}
}
},
"payer_info": {
"id": "35d4d1ec-4f9d-416d-acdc-d12f4bf0c6df",
"email": "tomhank@gmail.com",
"name": "Tom Hanks",
"billing_address": {
"phone": {
"country_code": "230",
"number": "57976041"
},
"line1": "18 Avenue",
"line2": "cassidy",
"city": "Rose-Hill",
"country_code": "MU",
"postal_code": "72101",
"state": ""
}
}
},
"transaction": {
"amount": {
"currency": "USD",
"total": "300"
},
"type": "1",
"mode": "1",
"items": [
{
"sku": "100299S",
"name": "Ultrawatch",
"description": "Smart watch",
"quantity": "1",
"price": "500",
"shipping": "",
"url": ""
},
{
"sku": "100269S",
"name": "Drone",
"description": "drone x",
"quantity": "1",
"price": "500",
"shipping": "",
"url": ""
}
],
"shipping_address": {
"phone": {}
},
"invoice_number": "123455"
},
"custom": {},
"risk_check": true,
"three_d": {},
"create_time": "2023-06-09T18:07:37Z",
"subscriptions": null
}
Note
For both PCI and non PCI merchants - As this is a subsequent merchant-initiated transaction, it is important to note that the CVV is not mandatory in this case