Please see the below best practices so that you stay up-to-date with the latest ACI Security Standards for the public APIs. According to the API documentation, all the data parameters require to be sent in the request body and not in the URL. 



What is the security concern?

What action the customer must take?

What ACI will do?

  • PSP / Merchant sending API requests with data parameters (including authentication parameters) in URL.
  • PSP / Merchant must send the Access-Token in the Authorization Bearer header. That will replace the use of the authentication parameters. The Access-Token will be taken from BIP at merchant / channel level. All the other data parameters are expected to go in the HTTPS request body. EntityId will stay as a mandatory parameter to indicate where to action the request.

Immediately:

  • ACI will allow accepting <access-token> in the Authorization Bearer header of all requests
  • ACI will continue to allow current authentication mechanism

At deadline time (will be communicated to customers in advance):

  • ACI will disallow accepting requests with data parameters (including authentication parameters) in the URL
  • ACI will disallow accepting requests with access-token not in the Authorization Bearer header

Please see below a couple of examples on how the requests look today and how they will change. This is not a comprehensive list of all OPP REST API requests supported but should give you a feeling about how to best tackle the integration API changes.

 

  

 NB: To see the cut off 2nd column - hover over columns and scroll to the side

 

 

How it is today?

How it should be tomorrow?

COPYandPAY integration guide

1. Prepare the checkout

Checkout request with data parameters in URL  Expand source 

curl -X POST https://test.oppwa.com/v1/checkouts? \
        authentication.userId=8a8294174b7ecb28014b9699220015cc \ 
        &authentication.password=sy6KJsT8 \
        &authentication.entityId=8a8294174b7ecb28014b9699220015ca \
        &amount=101.00 \
        &currency=EUR \
        &paymentType=DB

2. Create the payment form - no change

3. Get the payment status

Get payment status with data parameters in URL  Expand source 

curl -G https://test.oppwa.com/v1/checkouts/{id}/payment \
        authentication.userId=8a8294174b7ecb28014b9699220015cc \ 
        &authentication.password=sy6KJsT8 \
        &authentication.entityId=8a8294174b7ecb28014b9699220015ca

1. Prepare the checkout

Checkout request with data parameters in the request body  Expand source 

curl -X POST https://test.oppwa.com/v1/checkouts \
    -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
        -d "entityId=8a8294174b7ecb28014b9699220015ca" \
    -d "amount=92.00" \
    -d "currency=EUR" \
    -d "paymentType=DB"
 

2. Create the payment form - no change

3. Get the payment status

Get payment status with data parameters in the request body  Expand source 

curl -G https://test.oppwa.com/v1/checkouts/{id}/payment \

    -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
        -d "entityId=8a8294174b7ecb28014b9699220015ca"
 

Server-to-server synchronous workflow

Send an Initial Payment

Payment request with data parameters in URL  Expand source 

curl -X POST https://test.oppwa.com/v1/payments? \
        authentication.userId=8a8294174b7ecb28014b9699220015cc \
        &authentication.password=sy6KJsT8 \ 
        &authentication.entityId=8a8294174b7ecb28014b9699220015ca \ 
        &amount=101.00 \
        &currency=EUR \
        &paymentType=DB \
        &paymentBrand=VISA \
        &card.number=4200000000000000 \
        &card.holder=Miki Lauda \
        &card.expiryMonth=12 \
        &card.expiryYear=2020 \
        &card.cvv=123

Send an Initial Payment

Payment request with data parameters in the request body  Expand source 

curl -X POST https://test.oppwa.com/v1/payments \
        -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
        -d "entityId=8a8294174b7ecb28014b9699220015ca" \
    -d "amount=101.00" \
    -d "currency=EUR" \
    -d "paymentType=DB" \
    -d "paymentBrand=VISA" \
    -d "card.number=4200000000000000" \
    -d "card.holder=Miki Lauda" \
    -d "card.expiryMonth=12" \
    -d "card.expiryYear=2020" \
    -d "card.cvv=123"

Server-to-server asynchronous workflow

1. Send an Initial Payment

Payment request with data parameters in the URL  Expand source 

curl -X POST https://test.oppwa.com/v1/payments? \
        authentication.userId=8a8294174b7ecb28014b9699220015cc \
        &authentication.password=sy6KJsT8 \
        &authentication.entityId=8a8294174b7ecb28014b9699220015ca \
        &amount=101.00 \
        &currency=EUR \
        &paymentBrand=PAYPAL \
        &paymentType=PA \
        &shopperResultUrl=https://docs.oppwa.com/tutorials/server-to-server2. Redirect the shopper - no change

3. Get the payment status

Get payment status request with data parameters in URL  Expand source 

curl -G https://test.oppwa.com/v1/payments/{id} \
        authentication.userId=8a8294174b7ecb28014b9699220015cc \ 
        &authentication.password=sy6KJsT8 \
        &authentication.entityId=8a8294174b7ecb28014b9699220015ca

1. Send an Initial Payment

Payment with data parameters in the request body  Expand source 

curl -X POST https://test.oppwa.com/v1/payments \
        -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
        -d "entityId=8a8294174b7ecb28014b9699220015ca" \
    -d "amount=101.00" \
    -d "currency=EUR" \
    -d "paymentBrand=PAYPAL" \
    -d "paymentType=PA" \
    -d "shopperResultUrl=https://docs.oppwa.com/tutorials/server-to-server"2. Redirect the shopper - no change

3. Get the payment status

Get payment status request with data parameters in the request body  Expand source 

curl -G https://test.oppwa.com/v1/checkouts/{id}/payment \
    -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
        -d "entityId=8a8294174b7ecb28014b9699220015ca"

Server-to-server tokenization

Store the data as stand-alone

Registration request with data parameters in URL  Expand source 

curl -X POST https://test.oppwa.com/v1/registrations? \
        authentication.userId=8a8294174b7ecb28014b9699220015cc \
        &authentication.password=sy6KJsT8 \
        &authentication.entityId=8a8294174b7ecb28014b9699220015ca \
        &paymentBrand=VISA \
        &card.number=4200000000000000 \
        &card.holder=Miki Lauda \
        &card.expiryMonth=12 \
        &card.expiryYear=2020 \
        &card.cvv=123

Store the data as stand-alone

Registration request with data parameters in the request body  Expand source 

curl -X POST https://test.oppwa.com/v1/registration \
        -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
        -d "entityId=8a8294174b7ecb28014b9699220015ca" \
    -d "paymentBrand=VISA" \
    -d "card.number=4200000000000000" \
    -d "card.holder=Miki Lauda" \
    -d "card.expiryMonth=12" \
    -d "card.expiryYear=2020" \
    -d "card.cvv=123"

Backoffice payments

Refund a payment (capture, reversal would be similar)

Refund a payment with data parameters in URL  Expand source 

curl -X POST https://test.oppwa.com/v1/payments? \
        authentication.userId=8a8294174b7ecb28014b9699220015cc \
        &authentication.entityId=8a8294174b7ecb28014b9699220015ca \
        &authentication.password=sy6KJsT8 \
        &amount=10.00 \
        &currency=EUR \
        &paymentType=RF

Refund a payment (capture, reversal would be similar)

Refund a payment with data parameters in the request body  Expand source 

curl -X POST https://test.oppwa.com/v1/payments \
        -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
        -d "entityId=8a8294174b7ecb28014b9699220015ca" \
    -d "amount=10.00" \
    -d "currency=EUR" \
    -d "paymentType=RF"

Recurring payments

Sending the initial Payment

Initial payment request with data parameters in URL  Expand source 

curl -X POST https://test.oppwa.com/v1/payments \
        authentication.userId=8a8294174b7ecb28014b9699220015cc \
        &authentication.password=sy6KJsT8 \
        &authentication.entityId=8a8294174b7ecb28014b9699220015ca \
        &amount=92.00 \
        &currency=EUR \
        &paymentBrand=VISA \
        &paymentType=DB \
        &card.number=4200000000000000 \
        &card.holder=Miki Lauda \
        &card.expiryMonth=05 \
        &card.expiryYear=2020 \
        &card.cvv=123 \
        &recurringType=INITIAL \
        &createRegistration=true

Sending a repeated payment

Repeated payment request with data parameters in URL  Expand source 

curl -X POST https://test.oppwa.com/v1/registrations/{id}/payments \
        authentication.userId=8a8294174b7ecb28014b9699220015cc \
        &authentication.password=sy6KJsT8 \
        &authentication.entityId=8a8294174b7ecb28014b9699220015ca \
        &amount=92.00 \
        &currency=EUR \
        &paymentType=PA \
        &recurringType=REPEATED
 
 
 
 
 
 
 
 
 
 

Sending the initial Payment

Initial payment request with data parameters in the request body  Expand source 

curl -X POST https://test.oppwa.com/v1/payments \
        -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
        -d "entityId=8a8294174b7ecb28014b9699220015ca" \
        -d "amount=92.00" \
        -d "currency=EUR" \
        -d "paymentBrand=VISA" \
        -d "paymentType=DB" \
        -d "card.number=4200000000000000" \
        -d "card.holder=Miki Lauda" \
        -d "card.expiryMonth=05" \
        -d "card.expiryYear=2020" \
        -d "card.cvv=123" \
        -d "recurringType=INITIAL" \
        -d "createRegistration=true"

Sending a repeated payment

Repeated payment request with data parameters in the request body  Expand source 

curl -X POST https://test.oppwa.com/v1/payments \
        -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
        -d "entityId=8a8294174b7ecb28014b9699220015ca" \
        -d "amount=92.00" \
        -d "currency=EUR" \
        -d "paymentType=PA" \
        -d "recurringType=REPEATED"
 

ReD Shield integration guide

ReD Shield as a standalone risk service

Risk request with data parameters in URL  Expand source 

curl -X POST https://test.oppwa.com/v1/redShield \
        authentication.userId=8a8294174b7ecb28014b9699220015cc \
        &authentication.password=sy6KJsT8 \
        &authentication.entityId=8a8294174b7ecb28014b9699220015ca \
        &merchantTransactionId=123412341234 \
        &amount=92.00 \
        &currency=EUR \
        &paymentBrand=VISA \
        &card.number=4200000000000000 \
        &card.expiryMonth=12 \
        &card.expiryYear=2020 \
        &card.holder=Miki Lauda

ReD Shield as a standalone risk service

Risk request with data parameters in the request body  Expand source 

curl -X POST https://test.oppwa.com/v1/redShield \
        -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" \
        -d "entityId=8a8294174b7ecb28014b9699220015ca" \
        -d "merchantTransactionId=123412341234" \
        -d "amount=92.00" \
        -d "currency=EUR" \
        -d "paymentBrand=VISA" \
        -d "card.number=4200000000000000" \
        -d "card.expiryMonth=12" \
        -d "card.expiryYear=2020" \
        -d "card.holder=Miki Lauda"

Transaction Reports

Transaction Search Using paymentId

Transaction search using authentication data parameters in URL  Expand source 

curl -G https://test.oppwa.com/v1/query/{id}? \
        authentication.userId=8a8294174b7ecb28014b9699220015cc \
        &authentication.password=sy6KJsT8 \
        &authentication.entityId=8a8294174b7ecb28014b9699220015ca

Transaction Search Using paymentId

Transaction search with authentication details in header  Expand source 

curl -G https://test.oppwa.com/v1/query/{id}/payment? \
        entityId=8a8294174b7ecb28014b9699220015ca \
        -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg=" 

Scheduling

Cancel the schedule (scheduling payment would be similar)

Cancelling a scheduled payment with authentication data parameters in URL  Expand source 

curl -X DELETE https://test.oppwa.com/scheduling/v1/schedules/{id}? \
authentication.userId=8a8294174b7ecb28014b9699220015cc \
&authentication.password=sy6KJsT8 \
&authentication.entityId=8a8294174b7ecb28014b9699220015ca

Cancel the schedule (scheduling payment would be similar)

Cancelling a scheduled payment with authentication details in header  Expand source 

curl -X DELETE https://test.oppwa.com/scheduling/v1/schedules/{id}? \
        entityId=8a8294174b7ecb28014b9699220015ca \
        -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="