Read a Payment Transaction

You may read a Subscription when handling a push notification or for some other reason.

To check the status, or other details, you need to read the Payment Transaction:

Request
GET /api/v2/Payment/Transactions/PCI_AEVDQO42JC3YHO4PSAZ3CQJU4S0P5A HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Accept: application/json

If everything is fine, the API responds with 200 OK and the object representation of the Payment Transaction:

Payment Transaction
{
"object": "payment.transactions",
"id": "PCI_AEVDQO42JC3YHO4PSAZ3CQJU4S0P5A",
// ...
"subscription": {
"object": "payment.subscriptions",
"id": "SUB_33KBF85VJ2X72TDVJ642QEK42TQNAZ"
},
// ...
"trans_id": 35412359,
"product_id": 440,
"product": "PayPal",
// ...
"amount": 990,
"currency": "EUR",
"created": "2021-06-09T22:09:09+02:00",
"updated": "2021-06-09T22:09:09+02:00",
"description": "Abonnement news.example.com",
// ...
"status": 115,
"status_text": "Abo genehmigt",
"details": {
"cleared": "open",
"status": 115,
"status_text": "Abo genehmigt",
"status_simple": 11,
"status_simple_text": "subscription approved",
// ...
},
// ...
}

This signalizes a payment of €9.90.

A refunded or reversed PayPal payment differs from that in the negative amount, the payment product type, and a reference to the original transaction:

Payment Transaction
{
"object": "payment.transactions",
"id": "PCI_WMC2TN4PT66CY90TS8YZY34QK9W2N7",
// ...
"subscription": {
"object": "payment.subscriptions",
"id": "SUB_33KBF85VJ2X72TDVJ642QEK42TQNAZ"
},
"parents": [
{
"object": "payment.transactions",
"id": "PCI_AEVDQO42JC3YHO4PSAZ3CQJU4S0P5A",
"ref_type_id": 19,
"trans_id": 35448445
}
],
// ...
"product_id": 478,
"product": "PayPal Erstattung",
  // ...
"amount": -495,
"currency": "EUR",
"created": "2021-07-05T13:32:50+02:00",
"updated": "2021-07-05T13:33:24+02:00",
"description": "TA-Code 35412359 (09.06.21)|Refund TA-Code 35448447",
// ...
   "status": 6,
"status_text": "abgeschlossen",
"details": {
"cleared": "open",
   "status": 6,
"status_text": "abgeschlossen",
      "status_simple": 1,
"status_simple_text": "accepted",
// ...
},
  // ...
}

This signalizes a refund of €4.45 for the former incoming payment.

An explanation of the fields:

Field

Type

Meaning

object

string

Always "payment.transactions"

id

string

Object ID

subscription

object

Optional. The subscription, if if belongs to one.

subscription/object

string

Always "payment.subscriptions"

subscription/id

string

Object ID of the subscription

parents

array

Optional. Array of linked transactions, for instance the original Payment Transaction that has been refunded or reversed.

parents/{n}/object

string

Always "payment.transactions"

parents/{n}/id

string

Object ID of the referenced Payment Transaction

parents/{n}/ref_type_id

int

Reference type 19 to reference the refunded or reversed Payment Transaction

parents/{n}/trans_id

int

Transaction ID of the referenced Payment Transaction

product_id

int

Payment product; relevant so far:

  • 440, PayPal, for incoming payments

  • 478, PayPal Erstattung, for refunded or reverse payments

product

string

Product name

amount

int

Monetary amount in the smallest currency unit. Negative if it is payed back (refunded or reversed transaction)

currency

string

ISO three-letter currency code, like "EUR"

description

string

Description

status

int

Status ID

status_text

string

Status name

details/status

int

Same as status

details/status_text

string

Same as status_text

details/status_simple

int

Simple status ID

details/status_simple_text

string

Simple status text

When it comes to the status, we recommend:

  • to use the "simple status" (details/status_simple) for program decisions;

  • to display the normal status text (status_text) to the user.

These are the "simple statuses":

Text / ID

Meaning

Typical flow:

"created" (8)

Initial status of every transaction. The payment is not authorised, nor wanted to capture.

"authorized" (2)

The payment is authorised, but was not requested to capture yet.

"pending" (10)

The payment was requested to capture, but you must wait with delivery for status accepted. This status is always set when we wait for the advance payment. It is also used with other payment methods to perform an additional risk check.

"waiting for shipment" (14)

Only for invoice payment. The merchant needs to inform us about the shipment to let us capture the amount.

"accepted" (1)

The request for capture or for invoice payment was accepted. You can deliver now. (When you use invoice payment, you need to add the partial deliveries, and request the capture along with your final delivery.)

"paid" (9)

We have received the invoice payment.

Special circumstances:

"denied" (3)

The payment was rejected for some reason.

"issue" (4)

A problem occurred after the payment was accepted. For instance, the payer wanted a credit card charge back.

"issue_resolved" (6)

The problem is resolved. For instance, the charge back could be objected.

"refund" (7)

The payment is flagged for refund. It will be processed with our next bank cycle.

"void" (5)

The payment was cancelled, or refunded.

"on hold" (13)

The payout is blocked for some reason.

Authorisation for subscription payments:

"subscription approved" (11)

The transaction used to authorise further payments has been approved.

"subscription declined" (12)

The transaction used to authorise further payments has been declined.