Complete payer actions

POST

payments

status

{terminal_friendly_id}

{order_id}

{transaction_id}

payer-actions

{plan_id}

complete

cURL

curl --request POST \
  --url https://terminal.smartretry.com/v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete \
  --header 'Content-Type: application/json' \
  --header 'x-signature: <api-key>' \
  --header 'x-timestamp: <api-key>' \
  --data '
{
  "responses": [
    {
      "action": "UPDATE_EXPIRY_DATE",
      "expiry": {
        "month": "<string>",
        "year": "<string>"
      }
    }
  ]
}
'

import requests

url = "https://terminal.smartretry.com/v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete"

payload = { "responses": [
        {
            "action": "UPDATE_EXPIRY_DATE",
            "expiry": {
                "month": "<string>",
                "year": "<string>"
            }
        }
    ] }
headers = {
    "x-signature": "<api-key>",
    "x-timestamp": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-signature': '<api-key>',
    'x-timestamp': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    responses: [{action: 'UPDATE_EXPIRY_DATE', expiry: {month: '<string>', year: '<string>'}}]
  })
};

fetch('https://terminal.smartretry.com/v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://terminal.smartretry.com/v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'responses' => [
        [
                'action' => 'UPDATE_EXPIRY_DATE',
                'expiry' => [
                                'month' => '<string>',
                                'year' => '<string>'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-signature: <api-key>",
    "x-timestamp: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://terminal.smartretry.com/v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete"

	payload := strings.NewReader("{\n  \"responses\": [\n    {\n      \"action\": \"UPDATE_EXPIRY_DATE\",\n      \"expiry\": {\n        \"month\": \"<string>\",\n        \"year\": \"<string>\"\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-signature", "<api-key>")
	req.Header.Add("x-timestamp", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://terminal.smartretry.com/v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete")
  .header("x-signature", "<api-key>")
  .header("x-timestamp", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"responses\": [\n    {\n      \"action\": \"UPDATE_EXPIRY_DATE\",\n      \"expiry\": {\n        \"month\": \"<string>\",\n        \"year\": \"<string>\"\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://terminal.smartretry.com/v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-signature"] = '<api-key>'
request["x-timestamp"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"responses\": [\n    {\n      \"action\": \"UPDATE_EXPIRY_DATE\",\n      \"expiry\": {\n        \"month\": \"<string>\",\n        \"year\": \"<string>\"\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "accepted": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "reason_code": "SYSTEM/SUCCESSFUL",
  "instance": "<string>",
  "context": {}
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "reason_code": "SYSTEM/SUCCESSFUL",
  "instance": "<string>",
  "context": {}
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "reason_code": "SYSTEM/SUCCESSFUL",
  "instance": "<string>",
  "context": {}
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "reason_code": "SYSTEM/SUCCESSFUL",
  "instance": "<string>",
  "context": {}
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "reason_code": "SYSTEM/SUCCESSFUL",
  "instance": "<string>",
  "context": {}
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "reason_code": "SYSTEM/SUCCESSFUL",
  "instance": "<string>",
  "context": {}
}

Use this endpoint when a transaction is waiting for the payer to act and you collect the responses yourself. Submitting them resumes the transaction.

Flow

Read the pending actions

Call Transaction status. While the payer must act, the response includes pending_payer_actions, retry.plan_id, and payer_action_url.

Submit the responses

POST to this endpoint with retry.plan_id as plan_id. Send one entry in responses for each pending action, no more and no fewer.

Poll status

A 202 means SmartRetry accepted the responses. Call Transaction status again for the outcome.

Actions you can complete

Pending action	Response
`UPDATE_EXPIRY_DATE`	`{ "action": "UPDATE_EXPIRY_DATE", "expiry": { "month": "09", "year": "2030" } }`. Send it alone.
`APPROVE_CURRENCY_CHANGE`	`{ "action": "APPROVE_CURRENCY_CHANGE", "approved": true }`
`UPDATE_BILLING_ADDRESS`	`{ "action": "UPDATE_BILLING_ADDRESS", "address": { ... } }`

responses takes a single UPDATE_EXPIRY_DATE entry, or one or two entries from APPROVE_CURRENCY_CHANGE and UPDATE_BILLING_ADDRESS. Unknown fields are rejected.

Actions the payer completes on the hosted page

ENTER_SECURITY_CODE and CONTACT_BANK can’t be completed through this endpoint, because the payer must provide the security code and confirm the bank contact themselves. Send the payer to payer_action_url from the status response.

Example

curl --request POST \
  --url https://terminal.smartretry.com/v1/payments/status/ABC123/ORD8A3F2/TX8A3F2C/payer-actions/PLAN_ID/complete \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: complete-TX8A3F2C-1' \
  --header 'x-timestamp: 1767225600' \
  --header 'x-signature: <signature>' \
  --data '{"responses":[{"action":"UPDATE_EXPIRY_DATE","expiry":{"month":"09","year":"2030"}}]}'

202 Accepted

{ "accepted": true }

Errors

Status	Reason code	When it happens
`400`	`VALIDATION/...`	The body failed validation, for example an invalid expiry or address. The plan stays pending, so you can resubmit.
`401`	See Authentication	The request signature is missing or invalid.
`403`	`ROUTING/TERMINAL_RESOURCE_ACCESS_DENIED`	The transaction belongs to another merchant, or `order_id` doesn’t match.
`404`	`ROUTING/RECORD_NOT_FOUND`	The terminal or transaction doesn’t exist, or the plan is expired, already completed, or doesn’t match `plan_id`, or `responses` doesn’t match the pending actions exactly.
`409`	`ROUTING/RESOURCE_LOCKED`	Another operation holds the lock on the order. SmartRetry doesn’t wait. Retry after a short backoff.
`409`	`ROUTING/IDEMPOTENCY_CONFLICT`	The `Idempotency-Key` was reused with a different body.
`413`		The body is larger than 2 KB.
`503`	`ROUTING/RESOURCE_LOCKED`	A duplicate request with the same `Idempotency-Key` is still in flight and the wait timed out.

Each plan can be completed once. Without an Idempotency-Key, repeating a successful call returns 404. With the same key and body, SmartRetry replays the original 202. See Idempotency.

Authorizations

x-signature

string

header

required

Lowercase hex HMAC-SHA256 of {x-timestamp}.{METHOD}.{path_with_query}.{raw_body} keyed with your API secret. See https://www.smartretry.com/docs/authentication.

x-timestamp

string

header

required

Current Unix time in seconds; must be within 5 minutes of server time and match the value used in the signature.

Headers

idempotency-key

string

Optional idempotency key, scoped to terminal + matched route pattern. A replayed request returns the cached response with Idempotency-Replayed: true. Send it exactly once (a repeated header is rejected); 1-255 characters, letters, digits, _ and - only.

Required string length: 1 - 255

Pattern: ^[\w-]+$

Path Parameters

transaction_id

string

required

Required string length: 8

Pattern: ^[\dA-Za-z]{8}$

order_id

string

required

Required string length: 8

Pattern: ^[\dA-Za-z]{8}$

terminal_friendly_id

string

required

Required string length: 6

Pattern: ^[\dA-Za-z]{6}$

plan_id

string

required

Minimum string length: 1

Body

application/json

responses

required

Required array length: 1 element

Show child attributes

Response

Default Response

accepted

enum<boolean>

required

Available options:

true

cURL

curl --request POST \
  --url https://terminal.smartretry.com/v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete \
  --header 'Content-Type: application/json' \
  --header 'x-signature: <api-key>' \
  --header 'x-timestamp: <api-key>' \
  --data '
{
  "responses": [
    {
      "action": "UPDATE_EXPIRY_DATE",
      "expiry": {
        "month": "<string>",
        "year": "<string>"
      }
    }
  ]
}
'

import requests

url = "https://terminal.smartretry.com/v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete"

payload = { "responses": [
        {
            "action": "UPDATE_EXPIRY_DATE",
            "expiry": {
                "month": "<string>",
                "year": "<string>"
            }
        }
    ] }
headers = {
    "x-signature": "<api-key>",
    "x-timestamp": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-signature': '<api-key>',
    'x-timestamp': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    responses: [{action: 'UPDATE_EXPIRY_DATE', expiry: {month: '<string>', year: '<string>'}}]
  })
};

fetch('https://terminal.smartretry.com/v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://terminal.smartretry.com/v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'responses' => [
        [
                'action' => 'UPDATE_EXPIRY_DATE',
                'expiry' => [
                                'month' => '<string>',
                                'year' => '<string>'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-signature: <api-key>",
    "x-timestamp: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://terminal.smartretry.com/v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete"

	payload := strings.NewReader("{\n  \"responses\": [\n    {\n      \"action\": \"UPDATE_EXPIRY_DATE\",\n      \"expiry\": {\n        \"month\": \"<string>\",\n        \"year\": \"<string>\"\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-signature", "<api-key>")
	req.Header.Add("x-timestamp", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://terminal.smartretry.com/v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete")
  .header("x-signature", "<api-key>")
  .header("x-timestamp", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"responses\": [\n    {\n      \"action\": \"UPDATE_EXPIRY_DATE\",\n      \"expiry\": {\n        \"month\": \"<string>\",\n        \"year\": \"<string>\"\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://terminal.smartretry.com/v1/payments/status/{terminal_friendly_id}/{order_id}/{transaction_id}/payer-actions/{plan_id}/complete")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-signature"] = '<api-key>'
request["x-timestamp"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"responses\": [\n    {\n      \"action\": \"UPDATE_EXPIRY_DATE\",\n      \"expiry\": {\n        \"month\": \"<string>\",\n        \"year\": \"<string>\"\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "accepted": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "reason_code": "SYSTEM/SUCCESSFUL",
  "instance": "<string>",
  "context": {}
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "reason_code": "SYSTEM/SUCCESSFUL",
  "instance": "<string>",
  "context": {}
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "reason_code": "SYSTEM/SUCCESSFUL",
  "instance": "<string>",
  "context": {}
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "reason_code": "SYSTEM/SUCCESSFUL",
  "instance": "<string>",
  "context": {}
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "reason_code": "SYSTEM/SUCCESSFUL",
  "instance": "<string>",
  "context": {}
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "reason_code": "SYSTEM/SUCCESSFUL",
  "instance": "<string>",
  "context": {}
}

Overview

Statuses

Payments

Recurring

Future Transactions

Flow

Actions you can complete

Actions the payer completes on the hosted page

Example

Errors

Authorizations

Headers

Path Parameters

Body

Response

​Flow

​Actions you can complete

​Actions the payer completes on the hosted page

​Example

​Errors

Authorizations

Headers

Path Parameters

Body

Response

Flow

Actions you can complete

Actions the payer completes on the hosted page

Example

Errors