Reference Keys

The OrderReference field uniquely identifies a credit card payment in an InfoSystems database. It's automatically generated when the StartPayment method is called, and must be used by the client when calling CompletePayment (or other subsequent operations). The InfoSystems Payment API also passes it as a parameter to the return URL given to the provider payment window, with the name InfosoftOrderReference. This is the URL that the user will be redirected to after authorizing the payment.

The OrderReference is also included on the PaymentProcess object that's returned from the methods CompletePayment, CapturePayment, CancelPayment, QueryPayment and PerformAgreementPayment

The ProviderOrderReference field is the unique ID of an order in the database of an underlying provider. All the providers have this concept, but they differ in the details of when the ID is created. Server-oriented providers generate the ID during the StartPayment step, while client-oriented providers generate it the moment the customer authorizes the payment. If the underlying provider is server-oriented, you should almost never need to deal with the ProviderOrderReference directly, unless you want to make calls to the underlying provider that don't go through the InfoSystems Payment API. When the provider is client-oriented, it's your responsibility as a client of the InfoSystems Payment API to pass the parameter to the InfoSystems database using the UpdatePayment method. This is necessary for the API to be able to identify the payment in subsequent calls to CompletePayment, CapturePayment, CancelPayment or QueryPayment.

When the underlying provider is server-oriented, the ProviderOrderReference can already be seen on the PaymentProcess object returned from StartPayment. For client-oriented providers the field will be empty at that point, since the reference doesn't exist yet. It will be returned as part of the PaymentProcess object from CompletePayment, CapturePayment, CancelPayment and QueryPayment, provided that UpdatePayment has been called as described above (which is in any case necessary for any of those methods to work correctly).

Unlike the ProviderOrderReference, which is used by all providers, the ProviderTransactionReference is currently only applicable when the underlying provider is PayEx. See the article on provider differences for more details on this.

For PayEx, it's important to be aware of the distinction between orders and transactions. An order is created in the PayEx database when the StartPayment method is called, and a corresponding transaction is created when CompletePayment is called. PayEx will actually create a new transaction number each time Capture or Credit is called, but the InfoSystems Payment API currently only stores the initial transaction number returned from the Complete method. All the transaction numbers may be used to perform subsequent operations on the payment.

For all providers other than PayEx, the ProviderTransactionReference field can be ignored. It will be set to be the same as the ProviderOrderReference on the PaymentProcess object after the CompletePayment method has been called, and has no effect beyond this.

The AgreementReference is used to perform agreement payments with the PerformAgreementPayment method. For client-oriented providers, the agreement reference should be passed to the UpdatePayment just like the ProviderOrderReference. For server-oriented providers, the AgreementReference will be created either during StartPayment (PayEx) or CompletePayment (Netaxept), and will be retrieved automatically by the InfoSystems Payment API. The AgreementReference will be stored on the PaymentProcess object, and may be seen in calls to CompletePayment, CapturePayment, CancelPayment and QueryPayment.

Unlike the other reference keys, the ExternalOrderId is entirely optional. An arbitrary string (of a maximum of 255 characters) may be passed to StartPayment, and if it is, it will be stored in the InfoSystems database along with the payment that gets created. It can be seen on the PaymentProcess object returned from all subsequent calls that handle the payment in question.

The most likely use for the ExternalOrderId would be for connecting the InfoSystems Payment API payment to an item in a different database. It could for instance contain an order ID from an external shop system. Note that there is currently no way to search for payments by ExternalOrderId, and that in fact the ExternalOrderId is not required to be unique.

All the providers use different terms for the reference keys, and the InfoSystems Payment API has its own terminology on top of that. This table can be used to determine what provider field corresponds to a field in the InfoSystems Payment API. This table only includes the provider fields -- not the fields created by the InfoSystems Payment API or by its clients.

Reference

Other Resources