Cards & Wallets · Common features · Scheduler

Creating a Schedule

The key request to create a schedule is the same regardless of the mechanism chosen to create the schedule. This is documented on the Schedule Definition page.

The endpoints and their usages are documented below.

Creating a schedule while requesting an initial authorisation

A schedule can be attached to a transaction when it is initially requested. If the transaction is successful the schedule will be created, if the transaction is not successful it will not be created. If for some reason the schedule is not successfully created the transaction will be unaffected and will complete as expected. The cause of the error in the schedule creation will be returned in the response. The schedule can be re-created by creating a schedule on an existing transaction.

API examples

Sample Payment (for a new customer)
EndpointDefinition
POST /acceptor/rest/transactions/{instId}/payment
Request body
{
  "transaction": {
    "currency": "GBP",
    "amount": 1000.0,
    "commerceType": "MOTO",
    "recurring": true
  },
  "paymentMethod": {
    "card": {
      "pan": "9900000000005159",
      "cv2": "123",
      "expiryDate": "0130",
      "startDate": "1111",
      "cardType": "MC_DEBIT",
      "nickname": "John",
      "cardHolderName": "John Smith",
      "defaultCard": false
    }
  },
  "schedule": {
    "startDate": "2031-01-30",
    "pattern": {
      "dayOfMonth": 20
    }
  }
}
cURL
curl -X POST "{targetEnvironmentPath}/acceptor/rest/transactions/{instId}/payment" \
  -u "{apiUser}:{apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
  "transaction": {
    "currency": "GBP",
    "amount": 1000.0,
    "commerceType": "MOTO",
    "recurring": true
  },
  "paymentMethod": {
    "card": {
      "pan": "9900000000005159",
      "cv2": "123",
      "expiryDate": "0130",
      "startDate": "1111",
      "cardType": "MC_DEBIT",
      "nickname": "John",
      "cardHolderName": "John Smith",
      "defaultCard": false
    }
  },
  "schedule": {
    "startDate": "2031-01-30",
    "pattern": {
      "dayOfMonth": 20
    }
  }
}'
Response
HTTP/1.1 201

{
  "processing": {
    "authResponse": {
      "statusCode": "00",
      "message": "ACQUIRER OK",
      "authCode": "100000",
      "status": "AUTHORISED"
    },
    "route": "MCPE"
  },
  "paymentMethod": {
    "card": {
      "cardToken": "rusq9CmgRC2o39RYx9HAlA",
      "cardFingerprint": "0hbdt0r/7ofTCqA5qKilqtHeeJg=",
      "new": true,
      "cardType": "MC_DEBIT",
      "cardUsageType": "DEBIT",
      "cardCategory": "DEBIT",
      "cardScheme": "VISA",
      "maskedPan": "990000******5159",
      "expiryDate": "0130",
      "issuer": "Lloyds",
      "issuerCountry": "GBR",
      "cardHolderName": "John Smith",
      "cardNickname": "John",
      "validDate": "1111"
    },
    "paymentClass": "CARD"
  },
  "transaction": {
    "transactionId": "13501566687",
    "merchantRef": "mer_txn_1234556",
    "status": "SUCCESS",
    "type": "PAYMENT",
    "amount": 1000,
    "consumerSpend": 1000,
    "currency": "GBP",
    "transactionTime": "2021-01-06T12:25:30.902Z",
    "receivedTime": "2021-01-06T12:25:30.902Z",
    "channel": "MOTO"
  },
  "schedule": {
      "scheduleId": "GUID123456789010"
  }, 
  "outcome": {
    "status": "SUCCESS",
    "reasonCode": "S100",
    "reasonMessage": "Authorised"
  }
}
Sample Verification (with default card)
EndpointDefinition
POST /acceptor/rest/transactions/{instId}/verify
Request body
{
  "transaction" : {
    "currency" : "GBP",
    "commerceType" : "MOTO",
    "recurring": true
  },
  "paymentMethod" : {
    "fromCustomer" : {
      "cv2" : "123"
    }
  },
  "customer" : {
    "merchantRef" : "mer_cust_131241412"
  },
  "verification" : {
    "acquirerPaymentMethod" : true
  },
  "schedule": {
    "startDate": "2031-01-30",
    "timeOfDay": "13:30:00",
    "frequency": {
        "unit": "WEEK",
        "quantity": 2
    },
    "amounts": [
      5.00,
      3.00
    ],
    "terminator": {
        "endOn": "2031-06-30"
    },
    "retry": {
        "unit": "DAY",
        "maxRetries": 2
    }
  } 
}
cURL
curl -X POST "{targetEnvironmentPath}/acceptor/rest/transactions/{instId}/verify" \
  -u "{apiUser}:{apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
  "transaction" : {
    "currency" : "GBP",
    "commerceType" : "MOTO",
    "recurring": true
  },
  "paymentMethod" : {
    "fromCustomer" : {
      "cv2" : "123"
    }
  },
  "customer" : {
    "merchantRef" : "mer_cust_131241412"
  },
  "verification" : {
    "acquirerPaymentMethod" : true
  },
  "schedule": {
    "startDate": "2031-01-30",
    "timeOfDay": "13:30:00",
    "frequency": {
        "unit": "WEEK",
        "quantity": 2
    },
    "amounts": [
      5.00,
      3.00
    ],
    "terminator": {
        "endOn": "2031-06-30"
    },
    "retry": {
        "unit": "DAY",
        "maxRetries": 2
    }
  } 
}'
Response
HTTP/1.1 201

{
  "processing" : {
    "authResponse" : {
      "acquirerName" : "HSBC Merchant Services Domestic",
      "message" : "TEST AUTH",
      "authCode" : "9999",
      "gatewayMessage" : "TEST AUTH",
      "status" : "AUTHORISED"
    },
    "route" : "GATEWAY"
  },
  "paymentMethod" : {
    "registered" : true,
    "card" : {
      "cardToken" : "MT_wpL9AdPDQnyeVHoh74AhHQ",
      "new" : false,
      "cardType" : "VISA_DEBIT",
      "cardUsageType" : "DEBIT",
      "cardScheme" : "VISA",
      "cardCategory" : "CREDIT",
      "maskedPan" : "444433******1111",
      "expiryDate" : "0130",
      "issuer" : "DATACASH",
      "issuerCountry" : "GBR",
      "cardHolderName" : "John Smith",
      "cardNickname" : "John",
      "validDate" : "1111"
    },
    "paymentClass" : "CARD"
  },
  "customer" : {
    "id" : "10983",
    "merchantRef" : "mer_cust_131241412"
  },
  "transaction" : {
    "transactionId" : "13133368188",
    "merchantRef" : "mer_txn_1234556",
    "merchantDescription" : "Sample Transaction",
    "status" : "SUCCESS",
    "type" : "VERIFY",
    "transactionTime" : "2017-01-13T14:43:30.826Z",
    "receivedTime" : "2017-01-13T14:43:30.826Z"
  },
  "outcome" : {
    "status" : "SUCCESS",
    "reasonCode" : "S100",
    "reasonMessage" : "Authorised"
  },
  "schedule": {
      "scheduleId": "GUID123456789010"
  }
}

Creating a schedule while requesting a Repeat

A schedule can be created while requesting a repeat of a transaction. The schedule will be associated with the original, primary, transaction. If the transaction is successful the schedule will be created, if the transaction is not successful it will not be created. If for some reason the schedule is not successfully created the transaction will be unaffected and will complete as expected. The cause of the error in the schedule creation will be returned in the response. The schedule can be re-created by creating a schedule on an existing transaction.

API examples

Create Schedule while Requesting repeat
EndpointDefinition
POST /acceptor/rest/transactions/{instId}/{transactionId}/repeat
Request body
{
    "schedule" : {
        "startDate":"2031-09-15",
        "timeOfDay":"12:00:00",
        "fixed": ["2031-09-15","3031-11-15"],
        "terminator":{
            "episodeLimit":5,
            "endOn":"3031-11-15",
            "suspend":{
                "failureCount":3
             }
         },
        "retry":{
            "unit": "DAY",
            "quantity": 1,
            "maxRetries":3,
            "processWhileRetrying":false,
            "catchupAfterRetrying":true
        }
    }
}
cURL
curl -X POST "{targetEnvironmentPath}/acceptor/rest/transactions/{instId}/{transactionId}/repeat" \
  -u "{apiUser}:{apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule" : {
        "startDate":"2031-09-15",
        "timeOfDay":"12:00:00",
        "fixed": ["2031-09-15","3031-11-15"],
        "terminator":{
            "episodeLimit":5,
            "endOn":"3031-11-15",
            "suspend":{
                "failureCount":3
             }
         },
        "retry":{
            "unit": "DAY",
            "quantity": 1,
            "maxRetries":3,
            "processWhileRetrying":false,
            "catchupAfterRetrying":true
        }
    }
}'
Response
HTTP/1.1 201

{
  "processing": {
    "model": "MANAGE",
    "authResponse": {
      "acquirerName": "FDMS International",
      "gatewayReference": "111gbpfa2941311412749ACee1000z00",
      "gatewayCode": "000.000.000",
      "gatewayMessage": "Transaction succeeded",
      "status": "AUTHORISED"
    },
    "route": "PAYON"
  },
  "paymentMethod": {
    "registered": false,
    "card": {
      "cardFingerprint": "Q1MtYTRiZGIzODYtYzQ2My00NTRlLTljZjYtYzY0OTEzZjUwMmVj",
      "new": false,
      "cardType": "VISA_CREDIT",
      "cardUsageType": "CREDIT",
      "cardScheme": "VISA",
      "cardCategory": "CREDIT",
      "maskedPan": "990300******5131",
      "expiryDate": "0130",
      "issuer": "PAY360 TESTING",
      "issuerCountry": "GBR",
      "cardHolderName": "John Smith"
    },
    "paymentClass": "CARD",
    "reuse": {
      "storage": "EXISTING",
      "agreement": "INSTALMENT",
      "originalSchemeReference": "111gbp2633976043a3f84FMee1000z00",
      "receivedSchemeReference": "111gbpfa2941311412749ACee1000z00"
    }
  },
  "transaction": {
    "transactionId": "10393828218",
    "deferred": false,
    "instalment": true,
    "status": "SUCCESS",
    "stage": "COMPLETE",
    "type": "REPEAT",
    "amount": 1000,
    "consumerSpend": 1000,
    "currency": "GBP",
    "transactionTime": "2020-11-13T16:02:32.261Z",
    "receivedTime": "2020-11-13T16:02:32.261Z",
    "relatedTransaction": {
      "transactionId": "10393828217"
    },
    "customerInitiated": false
  },
  "outcome": {
    "status": "SUCCESS",
    "reasonCode": "S100",
    "reasonMessage": "Authorised"
  },
  "schedule": {
      "scheduleId": "GUID123456789010"
  }
}

Creating a schedule via the PaySuite Payment Page or Pay by Link

A schedule can be initiated as part of a hosted session initialisation request for the PaySuite Payment Page whether this is done directly or via a Pay by Link URL. If you would like information about the schedule to be displayed on the form this will need to be done by the skin.

API examples

Requesting a PaySuite Payment Page session
EndpointDefinition
POST /hosted/rest/sessions/{instId}/payments
Request body
{
  "session" : {
    "returnUrl" : {
      "url" : "http://www.example.com/hosted/transactionResult?ref=paymentHosted"
    }
  },
  "transaction" : {
    "merchantReference" : "paymentHosted",
    "money" : {
      "currency" : "GBP",
      "amount" : {
      	"fixed": 10.99
      }
    },
    "description" : "PaymentHosted",
    "recurring": true
  },
  "customer" : {
    "identity" : {
      "merchantCustomerId" : "customer1"
    },
    "details": {
    	"name": "Customer 1",
    	"address": {
    		"countryCode": "GBR"
    	}
    }
  },
  "schedule": {
    "startDate": "2031-01-30",
    "pattern": {
      "dayOfMonth": 15
    }
  }
}
cURL
curl -X POST "{targetEnvironmentPath}/hosted/rest/sessions/{instId}/payments" \
  -u "{apiUser}:{apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
  "session" : {
    "returnUrl" : {
      "url" : "http://www.example.com/hosted/transactionResult?ref=paymentHosted"
    }
  },
  "transaction" : {
    "merchantReference" : "paymentHosted",
    "money" : {
      "currency" : "GBP",
      "amount" : {
      	"fixed": 10.99
      }
    },
    "description" : "PaymentHosted",
    "recurring": true
  },
  "customer" : {
    "identity" : {
      "merchantCustomerId" : "customer1"
    },
    "details": {
    	"name": "Customer 1",
    	"address": {
    		"countryCode": "GBR"
    	}
    }
  },
  "schedule": {
    "startDate": "2031-01-30",
    "pattern": {
      "dayOfMonth": 15
    }
  }
}'
Response
HTTP/1.1 201 Created

{
  "sessionId": "SMjrRY-ABUwZNPawG1foxQWrn",
  "redirectUrl": "https://secure.mite.pay360.com/hosted/SMjrRY-ABUwZNPawG1foxQWrn/begin/SMjrRY-ABUwZNPawG1foxQWrn",
  "status": "SUCCESS"
}

Creating a schedule on an existing transaction

It is also possible to create a schedule on an existing successful transaction.

API examples

Create schedule on existing transaction
EndpointDefinition
POST /acceptor/rest/transactions/{instId}/{transactionId}/addSchedule
Request body
{
  "schedule": {
    "frequency": {
      "unit": "MONTH"
    },
    "amounts": [
      5.00,
      3.00
    ]
  }
}
cURL
curl -X POST "{targetEnvironmentPath}/acceptor/rest/transactions/{instId}/{transactionId}/addSchedule" \
  -u "{apiUser}:{apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": {
      "frequency": {
        "unit": "MONTH"
      },
      "amounts": [
        5.00,
        3.00
      ]
    }
  }'
Response
HTTP/1.1 201

{
  "processing": {
    "model": "MANAGE",
    "authResponse": {
      "acquirerName": "AIB Merchant Services",
      "gatewayReference": "111gbp72d7be32e37d992AMeeee10z00",
      "gatewayCode": "000.000.000",
      "gatewayMessage": "Transaction succeeded",
      "cv2Check": "MATCHED",
      "status": "AUTHORISED"
    },
    "route": "PAYON"
  },
  "paymentMethod": {
    "registered": false,
    "card": {
      "cardFingerprint": "Q1MtNTRmNzc2ZjQtNDE3NC00ZjNkLTgxYzAtYTFlYTE3MTlmMjUx",
      "new": true,
      "cardType": "MC_DEBIT",
      "cardUsageType": "DEBIT",
      "cardScheme": "MASTERCARD",
      "cardCategory": "DEBIT",
      "maskedPan": "990000******0010",
      "expiryDate": "1230",
      "issuer": "PAY360 TESTING",
      "issuerCountry": "GBR",
      "cardHolderName": "John Smith"
    }
  },
  "transaction": {
    "transactionId": "11760200728",
    "recurring": true,
    "status": "SUCCESS",
    "stage": "COMPLETE",
    "type": "PAYMENT",
    "amount": 10.00,
    "consumerSpend": 10.00,
    "currency": "GBP",
    "transactionTime": "2021-03-08T13:35:22.575Z",
    "receivedTime": "2021-03-08T13:35:22.575Z",
    "customerInitiated": true
  },
  "outcome": {
    "status": "SUCCESS",
    "reasonCode": "S100",
    "reasonMessage": "Authorised"
  },
  "schedule": {
    "scheduleId": "ff80818177f809ea0178122793b20013"
  }
}